fix(ci): install pytestarch in docling-compat workflow

The daily docling-compat job manually installed only pytest, pytest-asyncio
and httpx, which made test_architecture.py fail with ModuleNotFoundError:
no module named 'pytestarch' — wrongly opening 'Docling compatibility break'
issues. Align with ci.yml by installing requirements-test.txt instead.

.env.example

@@ -18,6 +18,10 @@
 # Max upload file size in MB (default: 50, 0 = unlimited)
 # MAX_FILE_SIZE_MB=50
 
+# Nginx body size limit — nginx format (default: 200M, 0 = unlimited).
+# Must be >= MAX_FILE_SIZE_MB. Backend MAX_FILE_SIZE_MB is the effective arbiter.
+# NGINX_MAX_BODY_SIZE=200M
+
 # Max pages per PDF (default: 0 = unlimited). Set to 20 for HF Spaces.
 # MAX_PAGE_COUNT=0
 
@@ -39,3 +43,17 @@
 
 # OpenSearch URL (used by docker-compose.dev.yml, auto-set to service name)
 # OPENSEARCH_URL=http://opensearch:9200
+
+# Embedding service URL (used by docker-compose.dev.yml, auto-set to service name)
+# EMBEDDING_URL=http://embedding:8001
+
+# Embedding model (default: all-MiniLM-L6-v2, used by the embedding service)
+# EMBEDDING_MODEL=all-MiniLM-L6-v2
+
+# Embedding vector dimension (default: 384 for Granite Embedding 30M / all-MiniLM-L6-v2)
+# EMBEDDING_DIMENSION=384
+
+# Neo4j — graph-native document structure (used by docker-compose.dev.yml)
+# NEO4J_URI=bolt://neo4j:7687
+# NEO4J_USER=neo4j
+# NEO4J_PASSWORD=changeme

.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
         with:
           python-version: "3.12"
           cache: pip
-          cache-dependency-path: document-parser/requirements.txt
+          cache-dependency-path: document-parser/requirements-test.txt
 
       - name: Install system dependencies
         run: sudo apt-get update && sudo apt-get install -y --no-install-recommends poppler-utils
@@ -37,8 +37,8 @@ jobs:
       - name: Install Python dependencies
         run: |
           pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -r requirements-test.txt
-          pip install pytest pytest-asyncio httpx ruff
+          pip install httpx ruff
 
       - name: Lint
         run: ruff check .

.github/workflows/docling-compat.yml

@@ -27,7 +27,7 @@ jobs:
         with:
           python-version: "3.12"
           cache: pip
-          cache-dependency-path: document-parser/requirements.txt
+          cache-dependency-path: document-parser/requirements-test.txt
 
       - name: Install system dependencies
         run: sudo apt-get update && sudo apt-get install -y --no-install-recommends poppler-utils
@@ -35,8 +35,8 @@ jobs:
       - name: Install pinned dependencies
         run: |
           pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -r requirements-test.txt
-          pip install pytest pytest-asyncio httpx
+          pip install httpx
 
       - name: Upgrade docling to latest
         id: versions

.github/workflows/release-gate.yml

@@ -353,6 +353,12 @@ jobs:
           exit-code: 1
           severity: CRITICAL
           output: /tmp/trivy-critical-${{ matrix.target }}.txt
+          trivyignores: .trivyignore.yaml
+          # `latest` instead of the action default — the previously hardcoded
+          # v0.69.3 was yanked from GitHub releases mid-run (2026-04-29) and
+          # broke the gate. Following Trivy stable is safer than chasing a
+          # specific tag that can vanish.
+          version: latest
 
       - name: Run Trivy — HIGH (informational)
         if: always()
@@ -363,6 +369,8 @@ jobs:
           exit-code: 0
           severity: HIGH
           output: /tmp/trivy-high-${{ matrix.target }}.txt
+          trivyignores: .trivyignore.yaml
+          version: latest
 
       - name: Annotate HIGH vulnerabilities
         if: always()

.gitignore

@@ -44,5 +44,8 @@ hs_err_pid*
 # Docker
 docker-compose.override.yml
 
+# Audit profiles (internal tooling)
+profiles/
+
 # E2E tests — Maven build outputs & Chrome user data
 e2e/**/target/

.trivyignore.yaml

@@ -0,0 +1,11 @@
+vulnerabilities:
+  - id: CVE-2026-40393
+    # No `paths:` constraint — Trivy reports OS-package CVEs against the
+    # package name (libgbm1, libgl1-mesa-dri, libglx-mesa0, mesa-libgallium),
+    # not against installed file paths. A `paths:` filter would silently
+    # fail to match and the ignore would be a no-op (which it was).
+    statement: >-
+      Mesa OOB read (fix: Mesa 25.3.6 / 26.0.1). No Debian 13 backport available.
+      Pulled transitively by libgl1 (required by OpenCV/RapidOCR). Tracked in #189
+      with follow-up to drop libgl1 via opencv-python-headless.
+    expired_at: 2026-06-30

CHANGELOG.md

@@ -4,11 +4,71 @@ All notable changes to Docling Studio will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [0.4.0] - Unreleased
+## [0.5.1] - 2026-04-30
+
+### Fixed
+
+- Nginx upload body cap raised from 5 MB to 200 MB (`NGINX_MAX_BODY_SIZE`, default `200M`); uploads larger than 5 MB no longer returned 413 before reaching the backend.
+
+## [0.5.0] - 2026-04-28
 
 ### Added
 
+- Reasoning-trace viewer: SQLite-backed graph built from `document_json`, iteration-by-iteration overlay on the document outline (StructureViewer + GraphView), bidirectional PDF ↔ graph focus
+- Live reasoning runner via [docling-agent](https://github.com/docling-project/docling-agent) (Ollama backend): `POST /api/documents/:id/reasoning` returns answer + iteration trace + convergence flag (gated by `REASONING_ENABLED`, off by default)
+- `LLMProvider` port abstraction with `OllamaProvider` adapter — opens the door to alternate LLM backends once docling-agent supports them
+- Neo4j graph storage pipeline: `TreeWriter` + `ChunkWriter` adapters, schema bootstrap, graph fetch endpoint, `Maintain` step with cytoscape-based graph visualization
+- Architecture decision record (ADR-001): graph visualization library choice and 200-page endpoint cap
+- Remote chunking: enabled in Docling Serve mode (previously local-only)
+- Hexagonal architecture tests powered by `pytestarch` (CI-enforced)
+- Centralized magic numbers for page dimensions, limits, and timeouts
+- Paste image size/type limits (env vars `MAX_PASTE_IMAGE_SIZE_MB`, `PASTE_ALLOWED_IMAGE_TYPES`); surfaced in `/api/health`
+
+### Changed
+
+- **Breaking — `RAG_*` env vars renamed to `REASONING_*`**: `RAG_ENABLED` → `REASONING_ENABLED`, `RAG_MODEL_ID` → `REASONING_MODEL_ID`. Health response field `ragAvailable` → `reasoningAvailable`. New `LLM_PROVIDER_TYPE` env var (default `ollama`) materializes the LLM-provider abstraction.
+- **Breaking — reasoning endpoint renamed `/rag` → `/reasoning`**: `POST /api/documents/:id/rag` is now `POST /api/documents/:id/reasoning`. Aligns with frontend `reasoning` feature naming.
+- `api/reasoning.py` refactored to depend on `ReasoningRunnerPort`; concrete `docling-agent` integration moved to `infra/docling_agent_reasoning.py` (clean architecture)
+- Frontend `reasoning` feature flag now reads `reasoningAvailable` from `/api/health`; sidebar entry hides when the backend is not wired (instead of failing with 503 on click)
+- Documented that `docker-compose.yml` ships dev-only defaults (Neo4j `changeme` password, OpenSearch `DISABLE_SECURITY_PLUGIN=true`); operators must harden their own production deployments
+- Backend logs a loud warning at boot if Neo4j is wired (`NEO4J_URI` set) with the default `changeme` password, so prod operators can't silently inherit it
+- `DocumentConverter` port exposes `supports_page_batching: bool` so the analysis service no longer relies on `isinstance(converter, ServeConverter)` (LSP fix)
+- `VectorStore` port gains a `ping()` method; `IngestionService.ping()` now goes through the port instead of reaching into `_vector_store._client` (encapsulation)
+- API path parameters renamed `{job_id}` → `{analysis_id}` across `api/analyses.py` and `api/ingestion.py` to align the OpenAPI surface with the user-facing terminology (URL paths unchanged)
+- Centralised `localStorage` keys (`docling-theme`, `docling-locale`) into `frontend/src/shared/storage/keys.ts` (`STORAGE_KEYS`)
+- Removed the dead `apiUrl` ref from the settings store and its orphan `settings.apiUrl` i18n entries
+- Document-status string `"uploaded"` extracted to `DOCUMENT_STATUS_UPLOADED` in `api/schemas.py`
+- PDF preview endpoint (`GET /api/documents/{id}/preview`) now offloads the synchronous file read + rasterisation to a worker thread (`asyncio.to_thread`), unblocking the FastAPI event loop
+
+### Fixed
+
+- Graph: collapse Docling `InlineGroup` and `Picture` children to avoid empty leaf nodes (#197)
+- Neo4j: rewrite `fetch_graph` using `CALL` subqueries for proper relationship traversal
+- CI: install `pytestarch` in backend tests job (#177)
+- CI: ignore CVE-2026-40393 (Mesa) with expiry — Debian has no backport (#190)
+- Reasoning: re-scroll PDF when re-clicking the active iteration
+- `infra/docling_tree.py:101` migrated `isinstance(bbox, (list, tuple))` to PEP 604 union (Ruff UP038)
+- Cross-feature integration test moved out of `features/history/` into `src/__tests__/integration/` so feature folders stay self-contained
+- Tightened terminal `assert X is not None` checks in domain/repo/service tests to compare the value (e.g. `isinstance(.., datetime)` after `mark_running()`/`mark_completed()`)
+
+## [0.4.0] - 2026-04-13
+
+### Added
+
+- Inline chunk text editing: double-click or edit button to modify chunk text, with save/cancel and "modified" badge
 - Docker Compose dev stack (`docker-compose.dev.yml`) with OpenSearch, Dashboards, hot-reload backend and Vite frontend
+- Soft-delete chunks: delete button with confirmation dialog, chunks hidden from UI but preserved in data
+- Vector index metadata schema: `IndexedChunk` domain model, OpenSearch mapping builder, configurable embedding dimension
+- `VectorStore` port (Protocol): `ensure_index`, `index_chunks`, `search_similar`, `get_chunks`, `delete_document`
+- OpenSearch adapter (`OpenSearchStore`): kNN vector search, full-text search, bulk indexing, document CRUD
+- Embedding microservice (`embedding-service/`): sentence-transformers REST API with batch processing and Dockerfile
+- `EmbeddingService` port and `EmbeddingClient` HTTP adapter for remote embedding generation
+- Orchestrated ingestion pipeline: Docling → chunking → embedding → OpenSearch indexing (idempotent)
+- Ingestion REST API: `POST /api/ingestion/{jobId}`, `DELETE /api/ingestion/{docId}`, `GET /api/ingestion/status`
+- Production docker-compose with OpenSearch and embedding service
+- E2E Karate test for full ingestion workflow (PDF → chunks in OpenSearch)
+- My Documents screen: search, filter (all/indexed/not indexed), sort (name/date), ingestion status badges
+- Ingest button in Studio: one-click ingestion from completed analysis with progress feedback
 
 ### Fixed
 

CONTRIBUTING.md

@@ -96,15 +96,43 @@ npx prettier --write src/   # auto-format
 ## Running Tests
 
 ```bash
-# Backend (199 tests)
+# Backend (377 tests)
 cd document-parser
 pytest tests/ -v
 
-# Frontend (129 tests)
+# Frontend (156 tests)
 cd frontend
 npm run test:run
 ```
 
+### E2E API (Karate)
+
+```bash
+# Generate test PDFs + start stack
+python e2e/generate-test-data.py
+docker compose up -d --wait
+
+# Run all API tests
+mvn test -f e2e/api/pom.xml
+
+# Or by tag: @smoke, @regression, @e2e
+mvn test -f e2e/api/pom.xml -Dkarate.options="--tags @smoke"
+```
+
+### E2E UI (Karate UI)
+
+```bash
+# Generate test PDFs + start stack (if not already running)
+python e2e/generate-test-data.py
+docker compose up -d --wait
+
+# Run critical UI tests (CI scope)
+mvn test -f e2e/ui/pom.xml -Dkarate.options="--tags @critical"
+
+# Run all UI tests (local scope)
+mvn test -f e2e/ui/pom.xml -Dkarate.options="--tags @ui"
+```
+
 All tests must pass before submitting a PR.
 
 ## Submitting Changes

Dockerfile

@@ -24,10 +24,11 @@ FROM python:3.12-slim AS base
 ARG APP_VERSION=dev
 ENV APP_VERSION=${APP_VERSION}
 
-# System deps: poppler (pdf2image), nginx
+# System deps: poppler (pdf2image), nginx, gettext-base (envsubst for nginx template)
 RUN apt-get update && apt-get install -y --no-install-recommends \
     poppler-utils \
     nginx \
+    gettext-base \
     && rm -rf /var/lib/apt/lists/*
 
 # Python deps (common)
@@ -41,8 +42,8 @@ COPY document-parser/ .
 # Frontend static files
 COPY --from=frontend-build /build/dist /usr/share/nginx/html
 
-# Nginx config
+# Nginx config (template stored outside sites-enabled to avoid nginx loading it raw)
-COPY nginx.conf /etc/nginx/sites-enabled/default
+COPY nginx.conf.template /etc/nginx/default.template
 
 # Non-root user
 RUN useradd --create-home --shell /bin/bash appuser
@@ -52,10 +53,11 @@ RUN mkdir -p /app/uploads /app/data && chown -R appuser:appuser /app
 
 ENV UPLOAD_DIR=/app/uploads
 ENV DB_PATH=/app/data/docling_studio.db
+ENV NGINX_MAX_BODY_SIZE=200M
 
 EXPOSE 3000
 
-CMD ["sh", "-c", "nginx && exec su appuser -c 'uvicorn main:app --host 127.0.0.1 --port 8000'"]
+CMD ["sh", "-c", "envsubst '${NGINX_MAX_BODY_SIZE}' < /etc/nginx/default.template > /etc/nginx/sites-enabled/default && nginx && exec su appuser -c 'uvicorn main:app --host 127.0.0.1 --port 8000'"]
 
 # --- Remote: lightweight, delegates to Docling Serve ---
 FROM base AS remote

README.md

@@ -13,6 +13,17 @@ Upload a PDF, configure the extraction pipeline, and visualize the results — t
 
 ![Docling Studio — Presentation](docs/screenshots/presentation.gif)
 
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=scub-france%2FDocling-Studio&type=timeline&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=scub-france/Docling-Studio&type=timeline&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=scub-france/Docling-Studio&type=timeline&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=scub-france/Docling-Studio&type=timeline&legend=top-left" />
+ </picture>
+</a>
+
 ## Features
 
 - **Home page** with quick upload and recent documents
@@ -20,9 +31,14 @@ Upload a PDF, configure the extraction pipeline, and visualize the results — t
 - **Configurable Docling pipeline** — OCR, table extraction, code/formula enrichment, picture classification & description, image generation
 - **Bounding box visualization** — color-coded element overlay directly on the PDF
 - **Per-page results** — right panel syncs with the current PDF page
+- **Chunking** — split extracted content into semantic chunks (hierarchical, hybrid, or page-based) with configurable token limits and inline editing
+- **Ingestion pipeline** — Docling → chunking → embedding → OpenSearch vector indexing (one-click from Studio)
+- **Graph storage (Neo4j)** — full DoclingDocument tree (sections, paragraphs, tables, pages, chunks) mirrored as a graph with `PARENT_OF`, `NEXT`, `ON_PAGE`, `HAS_CHUNK`, `DERIVED_FROM` relations, with an in-app graph view powered by Cytoscape.js
 - **Markdown & HTML export** of extracted content
-- **Document management** — upload, list, delete
+- **Document management** — upload, list, delete, search, filter by indexing status
 - **Analysis history** — re-visit and open past analyses
+- **Upload limits** — configurable max file size and max page count per document
+- **Rate limiting** — configurable requests per minute per IP
 - **Dark / Light theme** and **FR / EN** localization
 
 
@@ -43,7 +59,7 @@ Upload a PDF, configure the extraction pipeline, and visualize the results — t
 | **frontend** | Vue 3, TypeScript, Vite, Pinia | UI, PDF viewer, results display |
 | **document-parser** | FastAPI, Docling, SQLite, pdf2image | REST API, document parsing, storage |
 
-### Backend structure (clean architecture)
+### Backend structure (hexagonal architecture — ports & adapters)
 
 ```
 document-parser/
@@ -63,7 +79,7 @@ document-parser/
 ├── services/                 # Use case orchestration
 │   ├── document_service.py   # Upload, delete, preview
 │   └── analysis_service.py   # Async Docling processing
-└── tests/                    # 199 tests (pytest)
+└── tests/                    # 377 tests (pytest)
 ```
 
 ### Frontend structure (feature-based)
@@ -87,14 +103,24 @@ frontend/src/
 
 ## Quick Start
 
-Docling Studio ships two Docker image variants:
+One command, nothing else to install:
+
+```bash
+docker run -p 3000:3000 ghcr.io/scub-france/docling-studio:latest-local
+```
+
+Open [http://localhost:3000](http://localhost:3000), upload a PDF, and get results. That's it.
+
+> **Note:** The first analysis takes longer as Docling downloads its ML models (~400 MB). Subsequent runs are fast.
+
+### Image variants
 
 | Variant | Image tag | Size | Description |
 |---------|-----------|------|-------------|
+| **local** | `latest-local` | ~1.9 GB | Full — runs Docling in-process, CPU-only |
 | **remote** | `latest-remote` | ~270 MB | Lightweight — delegates to an external [Docling Serve](https://github.com/DS4SD/docling-serve) instance |
-| **local** | `latest-local` | ~1.9 GB | Full — runs Docling in-process, CPU-only (downloads ML models on first run) |
 
-### Docker — remote mode (fastest)
+For remote mode:
 
 ```bash
 docker run -p 3000:3000 \
@@ -102,27 +128,17 @@ docker run -p 3000:3000 \
   ghcr.io/scub-france/docling-studio:latest-remote
 ```
 
-### Docker — local mode (self-contained)
+### Docker Compose
-
-```bash
-docker run -p 3000:3000 ghcr.io/scub-france/docling-studio:latest-local
-```
-
-> **Note:** The first analysis takes longer as Docling downloads its ML models (~400 MB). Subsequent runs are fast.
-
-Open [http://localhost:3000](http://localhost:3000)
-
-### Docker Compose (for development)
 
 ```bash
 git clone https://github.com/scub-france/Docling-Studio.git
 cd Docling-Studio
 
-# Local mode (default)
+# Simple mode (backend + frontend only)
 docker compose up --build
 
-# Remote mode
+# With ingestion pipeline (OpenSearch + embeddings)
-CONVERSION_MODE=remote DOCLING_SERVE_URL=http://your-docling-serve:5001 docker compose up --build
+docker compose --profile ingestion -f docker-compose.yml -f docker-compose.ingestion.yml up --build
 ```
 
 ### Local Development
@@ -151,12 +167,12 @@ npm run dev
 ### Running Tests
 
 ```bash
-# Backend (199 tests)
+# Backend (377 tests)
 cd document-parser
 pip install pytest pytest-asyncio httpx
 pytest tests/ -v
 
-# Frontend (129 tests)
+# Frontend (156 tests)
 cd frontend
 npm run test:run
 ```
@@ -191,6 +207,145 @@ All configuration is done via environment variables. See [`.env.example`](.env.e
 | `UPLOAD_DIR` | `./uploads` | File storage directory |
 | `DB_PATH` | `./data/docling_studio.db` | SQLite database path |
 | `CONVERSION_TIMEOUT` | `600` | Max seconds for a single Docling conversion |
+| `BATCH_PAGE_SIZE` | `10` | Pages per batch (`0` = process all at once) |
+| `MAX_FILE_SIZE_MB` | `50` | Maximum upload file size in MB (`0` = unlimited) |
+| `MAX_PAGE_COUNT` | `0` | Maximum number of pages per document (`0` = unlimited) |
+| `NGINX_MAX_BODY_SIZE` | `200M` | Nginx request body limit — nginx format (`200M`, `0` = unlimited). Must be ≥ `MAX_FILE_SIZE_MB`. |
+| `RATE_LIMIT_RPM` | `100` | Max requests per minute per IP (`0` = disabled) |
+
+## Upload Limits
+
+Docling Studio enforces configurable limits on uploaded documents to protect the server against oversized files and long-running analyses:
+
+- **`MAX_FILE_SIZE_MB`** (default `50`) — rejects uploads exceeding this size. Validated at two levels: early `Content-Length` check and streaming byte count.
+- **`MAX_PAGE_COUNT`** (default `0` = unlimited) — rejects documents with more pages than allowed. Useful on shared instances or Hugging Face Spaces to cap processing time.
+- **`NGINX_MAX_BODY_SIZE`** (default `200M`) — nginx-level body cap, applied before the request reaches the backend. Defaults to `200M` so `MAX_FILE_SIZE_MB` is always the effective limit. Use nginx format (`50M`, `1G`, `0` for unlimited).
+
+Both application limits are exposed in the `/api/health` endpoint so the frontend can display them to the user before upload. Set either to `0` to disable the corresponding check.
+
+## Ingestion Pipeline (opt-in)
+
+Docling Studio can optionally index extracted chunks into [OpenSearch](https://opensearch.org/) for vector and full-text search. This requires two additional services (OpenSearch + embedding) and is **disabled by default**.
+
+To enable ingestion with Docker Compose:
+
+```bash
+docker compose --profile ingestion \
+  -f docker-compose.yml -f docker-compose.ingestion.yml \
+  up --build
+```
+
+When ingestion is enabled, the UI shows:
+- An **Ingest** button in Studio to push chunks to OpenSearch
+- An **OpenSearch** connection status badge in the sidebar
+- **Indexed / Not indexed** filters on the Documents page
+- A **Search** page for full-text and vector search across indexed documents
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENSEARCH_URL` | — | OpenSearch endpoint (empty = ingestion disabled) |
+| `EMBEDDING_URL` | — | Embedding service endpoint (empty = ingestion disabled) |
+| `EMBEDDING_DIMENSION` | `384` | Vector dimension (must match embedding model) |
+
+## Graph storage with Neo4j (opt-in)
+
+Docling Studio can mirror the full **DoclingDocument tree** into a [Neo4j](https://neo4j.com/) graph: sections, paragraphs, tables, figures, pages, and chunks all become first-class nodes connected by `HAS_ROOT`, `PARENT_OF`, `NEXT`, `ON_PAGE`, `HAS_CHUNK`, and `DERIVED_FROM` edges. This enables queries that are impossible with a flat chunk store — navigating a document's outline, finding all tables under a given section, or tracing a chunk back to its source elements.
+
+Enable Neo4j with the ingestion profile (it ships alongside OpenSearch):
+
+```bash
+docker compose --profile ingestion \
+  -f docker-compose.yml -f docker-compose.ingestion.yml \
+  up --build
+```
+
+The Neo4j Browser is available at <http://localhost:7474> (user `neo4j`, password `changeme` by default).
+
+### Schema at a glance
+
+```mermaid
+graph TD
+    D[Document] -->|HAS_ROOT| SH[SectionHeader]
+    D -->|HAS_CHUNK| C[Chunk]
+    SH -->|PARENT_OF| P[Paragraph]
+    SH -->|PARENT_OF| T[Table]
+    P -->|NEXT| T
+    P -->|ON_PAGE| PG[Page]
+    T -->|ON_PAGE| PG
+    C -->|DERIVED_FROM| P
+    C -->|DERIVED_FROM| T
+```
+
+### Example Cypher queries
+
+Find all "Methods" sections across documents (impossible in vector-only stores):
+
+```cypher
+MATCH (d:Document)-[:HAS_ROOT]->(:Element)-[:PARENT_OF*]->(s:SectionHeader)
+WHERE toLower(s.text) CONTAINS 'method'
+RETURN d.title, s.text, s.level
+```
+
+Get the parent section and sibling elements of a chunk (context for RAG):
+
+```cypher
+MATCH (c:Chunk {id: $chunk_id})-[:DERIVED_FROM]->(e:Element)
+MATCH (e)<-[:PARENT_OF]-(parent:Element)-[:PARENT_OF]->(sibling:Element)
+RETURN parent, collect(sibling) AS siblings
+```
+
+List all tables from documents ingested from an `invoices/` path:
+
+```cypher
+MATCH (d:Document)-[:HAS_ROOT]->(:Element)-[:PARENT_OF*]->(t:Table)
+WHERE d.source_uri CONTAINS 'invoices/'
+RETURN d.title, t.caption, t.cells_json
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NEO4J_URI` | — | Neo4j Bolt endpoint (empty = graph storage disabled) |
+| `NEO4J_USER` | `neo4j` | Neo4j username |
+| `NEO4J_PASSWORD` | `changeme` | Neo4j password |
+
+The in-app **Graph** tab (under *Results*) renders the per-document graph with [Cytoscape.js](https://js.cytoscape.org/) (see [ADR-001](docs/architecture/adrs/ADR-001-graph-visualization-library.md) for the library choice). Documents with more than **200 pages** return `HTTP 413` from `GET /api/documents/{id}/graph`; pagination ships in v0.6.
+
+## Live Reasoning (opt-in, R&D)
+
+Docling Studio can run [docling-agent](https://github.com/docling-project/docling-agent)'s Chunkless RAG loop against an analyzed document and return a full **reasoning trace** — the path the agent walked through the document outline, with the section reference / rationale / answer for each iteration. The trace is overlaid on the document graph so you can *see* how the agent navigated the structure.
+
+Disabled by default — pulls heavy deps (`docling-agent`, `mellea`, ~60 MB) and needs a reachable Ollama instance with the target model already pulled.
+
+### Enable
+
+```bash
+export REASONING_ENABLED=true
+export OLLAMA_HOST=http://localhost:11434      # default
+export REASONING_MODEL_ID=gpt-oss:20b           # any model already pulled in Ollama
+# Optional, future-proof — only "ollama" is realizable today (see Architecture below):
+export LLM_PROVIDER_TYPE=ollama
+```
+
+Then `pip install docling-agent mellea` (or use the `local` Docker image which bundles them) and restart the backend. The frontend reads `reasoningAvailable` from `/api/health` and hides the **Reasoning** sidebar entry when the runner isn't wired — so users never click through to a 503.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REASONING_ENABLED` | `false` | Master switch — `true` to enable the live runner |
+| `OLLAMA_HOST` | `http://localhost:11434` | Ollama daemon URL |
+| `REASONING_MODEL_ID` | `gpt-oss:20b` | Default model id (per-call override allowed via the API) |
+| `LLM_PROVIDER_TYPE` | `ollama` | LLM backend selector — only `ollama` is supported today |
+
+### Architecture
+
+The reasoning subsystem is wired through a `ReasoningRunner` port (`document-parser/domain/ports.py`) and an `LLMProvider` abstraction:
+
+- `domain/ports.py` defines `ReasoningRunner`, `LLMProvider`, `ReasoningParseError` (no third-party imports)
+- `domain/value_objects.py` defines `LLMProviderType`, `ReasoningResult`, `ReasoningIteration`
+- `infra/llm/ollama_provider.py` implements `LLMProvider` for Ollama
+- `infra/docling_agent_reasoning.py` implements `ReasoningRunner` using docling-agent + mellea — all upstream coupling is here, including the `_rag_loop` workaround tracked at [docling-agent#26](https://github.com/docling-project/docling-agent/issues/26)
+- `api/reasoning.py` consumes `app.state.reasoning_runner` — zero coupling to docling-agent
+
+This makes alternate LLM backends a question of adding new `LLMProvider` adapters once docling-agent (or a replacement) supports them upstream.
 
 ## CI / Release
 

docker-compose.dev.yml

@@ -9,6 +9,26 @@
 # =============================================================================
 
 services:
+  # --- Neo4j (graph-native document structure) ---
+  neo4j:
+    image: neo4j:5.15-community
+    environment:
+      NEO4J_AUTH: ${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-changeme}
+      NEO4J_server_memory_heap_initial__size: 512m
+      NEO4J_server_memory_heap_max__size: 1g
+    ports:
+      - "7474:7474"
+      - "7687:7687"
+    volumes:
+      - neo4j_data:/data
+      - neo4j_logs:/logs
+    healthcheck:
+      test: ["CMD-SHELL", "cypher-shell -u $${NEO4J_USER:-neo4j} -p $${NEO4J_PASSWORD:-changeme} 'RETURN 1' || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
   # --- OpenSearch (single-node, security disabled for local dev) ---
   opensearch:
     image: opensearchproject/opensearch:2
@@ -38,6 +58,25 @@ services:
       opensearch:
         condition: service_healthy
 
+  # --- Embedding service (sentence-transformers) ---
+  embedding:
+    build:
+      context: ./embedding-service
+    ports:
+      - "8001:8001"
+    environment:
+      EMBEDDING_MODEL: ${EMBEDDING_MODEL:-all-MiniLM-L6-v2}
+      EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-64}
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:8001/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    deploy:
+      resources:
+        limits:
+          memory: 2g
+
   # --- Backend (FastAPI with hot-reload) ---
   document-parser:
     build:
@@ -55,12 +94,20 @@ services:
       DOCLING_SERVE_API_KEY: ${DOCLING_SERVE_API_KEY:-}
       RATE_LIMIT_RPM: ${RATE_LIMIT_RPM:-100}
       MAX_FILE_SIZE_MB: ${MAX_FILE_SIZE_MB:-50}
-      BATCH_PAGE_SIZE: ${BATCH_PAGE_SIZE:-0}
+      BATCH_PAGE_SIZE: ${BATCH_PAGE_SIZE:-10}
       OPENSEARCH_URL: http://opensearch:9200
+      EMBEDDING_URL: http://embedding:8001
+      NEO4J_URI: bolt://neo4j:7687
+      NEO4J_USER: ${NEO4J_USER:-neo4j}
+      NEO4J_PASSWORD: ${NEO4J_PASSWORD:-changeme}
     command: ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
     depends_on:
       opensearch:
         condition: service_healthy
+      embedding:
+        condition: service_healthy
+      neo4j:
+        condition: service_healthy
     deploy:
       resources:
         limits:
@@ -83,6 +130,8 @@ services:
 
 volumes:
   opensearch_data:
+  neo4j_data:
+  neo4j_logs:
   uploads_data:
   db_data:
   frontend_node_modules:

docker-compose.ingestion.yml

@@ -0,0 +1,19 @@
+# Override to enable the ingestion pipeline (OpenSearch + embeddings).
+#
+# Usage:
+#   docker compose --profile ingestion -f docker-compose.yml -f docker-compose.ingestion.yml up --build
+#
+# This wires the backend to the OpenSearch and embedding services started
+# by the "ingestion" profile and ensures they are healthy before the
+# backend starts.
+
+services:
+  document-parser:
+    environment:
+      OPENSEARCH_URL: http://opensearch:9200
+      EMBEDDING_URL: http://embedding:8001
+    depends_on:
+      opensearch:
+        condition: service_healthy
+      embedding:
+        condition: service_healthy

docker-compose.yml

@@ -1,4 +1,90 @@
+# =============================================================================
+# Docling Studio — local development / quick-start compose.
+#
+# DEV DEFAULTS — NOT PRODUCTION-READY.
+# This file ships sensible defaults for `docker compose up` to "just work" on
+# a developer laptop. It is NOT a production deployment template:
+#   - Neo4j boots with `NEO4J_PASSWORD=changeme` if the env var is unset.
+#   - OpenSearch runs single-node with `DISABLE_SECURITY_PLUGIN=true`
+#     (no TLS, no auth). Fine for local indexing experiments, never for
+#     anything reachable from outside `localhost`.
+#   - No HTTPS termination, no reverse-proxy hardening, no rate limit on
+#     the embedding/OpenSearch services, ports bound to all interfaces.
+#
+# Operators running their own Docling Studio instance MUST:
+#   1. Override `NEO4J_PASSWORD` (and rotate it) — see `.env.example`.
+#   2. Re-enable the OpenSearch security plugin and configure TLS/users —
+#      see https://opensearch.org/docs/latest/security/.
+#   3. Bind sensitive services to internal networks only, terminate TLS at
+#      a reverse proxy, and align CORS_ORIGINS / RATE_LIMIT_RPM with the
+#      deployment surface.
+#
+# The audit pipeline expects this file to flag the dev defaults as such —
+# don't silently strengthen them here without also updating the dev DX.
+# =============================================================================
+
 services:
+  # --- Neo4j (graph-native document structure) ---
+  # Dev-only auth: NEO4J_PASSWORD defaults to "changeme". Override in
+  # `.env` (or any orchestrator secret store) before exposing this stack.
+  neo4j:
+    profiles: ["ingestion"]
+    image: neo4j:5.15-community
+    environment:
+      NEO4J_AUTH: ${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-changeme}
+      NEO4J_server_memory_heap_initial__size: 512m
+      NEO4J_server_memory_heap_max__size: 1g
+    volumes:
+      - neo4j_data:/data
+      - neo4j_logs:/logs
+    healthcheck:
+      test: ["CMD-SHELL", "cypher-shell -u $${NEO4J_USER:-neo4j} -p $${NEO4J_PASSWORD:-changeme} 'RETURN 1' || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  # --- OpenSearch (single-node, security DISABLED — DEV ONLY) ---
+  # `DISABLE_SECURITY_PLUGIN: "true"` removes auth, TLS, and audit logging.
+  # This is fine for a local dev cluster bound to 127.0.0.1; it is NOT safe
+  # for anything reachable from another host. For production, drop this
+  # var, switch to a hardened image, and configure users + TLS:
+  # https://opensearch.org/docs/latest/security/configuration/
+  opensearch:
+    profiles: ["ingestion"]
+    image: opensearchproject/opensearch:2
+    environment:
+      discovery.type: single-node
+      DISABLE_SECURITY_PLUGIN: "true"
+      OPENSEARCH_JAVA_OPTS: "-Xms512m -Xmx512m"
+    volumes:
+      - opensearch_data:/usr/share/opensearch/data
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:9200/_cluster/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  # --- Embedding service (sentence-transformers) ---
+  embedding:
+    profiles: ["ingestion"]
+    build:
+      context: ./embedding-service
+    environment:
+      EMBEDDING_MODEL: ${EMBEDDING_MODEL:-all-MiniLM-L6-v2}
+      EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-64}
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:8001/health || exit 1"]
+      interval: 15s
+      timeout: 10s
+      retries: 20
+      start_period: 120s
+    deploy:
+      resources:
+        limits:
+          memory: 2g
+
+  # --- Backend (FastAPI) ---
   document-parser:
     build:
       context: ./document-parser
@@ -14,20 +100,31 @@ services:
       DOCLING_SERVE_API_KEY: ${DOCLING_SERVE_API_KEY:-}
       RATE_LIMIT_RPM: ${RATE_LIMIT_RPM:-100}
       MAX_FILE_SIZE_MB: ${MAX_FILE_SIZE_MB:-50}
-      BATCH_PAGE_SIZE: ${BATCH_PAGE_SIZE:-0}
+      BATCH_PAGE_SIZE: ${BATCH_PAGE_SIZE:-10}
+      OPENSEARCH_URL: ${OPENSEARCH_URL:-}
+      EMBEDDING_URL: ${EMBEDDING_URL:-}
+      NEO4J_URI: ${NEO4J_URI:-}
+      NEO4J_USER: ${NEO4J_USER:-neo4j}
+      NEO4J_PASSWORD: ${NEO4J_PASSWORD:-changeme}
     deploy:
       resources:
         limits:
           memory: 4g
 
+  # --- Frontend (nginx) ---
   frontend:
     build:
       context: ./frontend
     ports:
       - "3000:80"
+    environment:
+      NGINX_MAX_BODY_SIZE: ${NGINX_MAX_BODY_SIZE:-200M}
     depends_on:
       - document-parser
 
 volumes:
+  opensearch_data:
+  neo4j_data:
+  neo4j_logs:
   uploads_data:
   db_data:

docs/architecture.md

@@ -8,7 +8,7 @@ Two services communicating via REST. The frontend is a Vue 3 SPA served by Nginx
 
 ### Zooming into the backend
 
-The schema above shows the macro view. Inside the backend, the code follows a **Clean Architecture** with strict layer boundaries:
+The schema above shows the macro view. Inside the backend, the code follows a **Hexagonal Architecture** (ports & adapters) with strict layer boundaries:
 
 ```
 ┌──────────────────────────────────────────────────────┐
@@ -34,9 +34,9 @@ The schema above shows the macro view. Inside the backend, the code follows a **
 
 Dependencies flow **inward**: `api → services → domain`. The domain layer has zero knowledge of HTTP or database.
 
-## Backend — Clean Architecture
+## Backend — Hexagonal Architecture (ports & adapters)
 
-The backend follows a strict layered architecture. Dependencies flow inward: API → Services → Domain. The domain layer has zero knowledge of HTTP or database.
+The backend follows the hexagonal / ports-and-adapters pattern. The domain layer defines **ports** (abstract protocols in `domain/ports.py`); `infra/` provides **adapters** that implement them. Dependencies flow inward: API → Services → Domain. The domain layer has zero knowledge of HTTP, database, or any framework.
 
 ```
 document-parser/

docs/architecture/adr-guide.md

@@ -34,7 +34,7 @@ These decisions were made before the ADR process was introduced. They are docume
 
 | Decision | Rationale | Date |
 |----------|-----------|------|
-| Clean Architecture (hexagonal) for backend | Decouple domain from framework — enable converter swapping (local/remote) | 2025-01 |
+| Hexagonal Architecture (ports & adapters) for backend | Decouple domain from framework — enable converter swapping (local/remote) via ports | 2025-01 |
 | FastAPI over Django | Async-first, lightweight, Pydantic-native — better fit for a single-purpose API | 2025-01 |
 | Vue 3 + Pinia over React | Composition API + built-in reactivity — smaller bundle for this use case | 2025-01 |
 | SQLite over PostgreSQL | Single-file DB, zero ops — appropriate for a document processing tool | 2025-01 |

docs/architecture/adrs/ADR-001-graph-visualization-library.md

@@ -0,0 +1,142 @@
+# ADR-001: Graph visualization library for the Neo4j graph view
+
+**Date**: 2026-04-17
+**Status**: Proposed
+**Deciders**: Pier-Jean Malandrino
+
+## Context
+
+v0.5.0 introduces Neo4j as a graph-native storage layer for parsed documents
+(see [docs/design/neo4j-integration.md](../../design/neo4j-integration.md)
+and [#186](https://github.com/scub-france/Docling-Studio/issues/186)). We need
+an in-app visualization of that graph: the `DoclingDocument` tree as rendered
+in Neo4j, with nodes colored by element type (`SectionHeader`, `Paragraph`,
+`Table`, `Figure`, `ListItem`, `Formula`) and edges (`PARENT_OF`, `NEXT`,
+`ON_PAGE`, `HAS_CHUNK`, `DERIVED_FROM`).
+
+The view lives in the existing Vue 3 debug panel. It is the **primary demo
+artifact** for the Hackernoon hackathon (Neo4j partner), so polish matters as
+much as correctness.
+
+### Constraints
+
+- Vue 3 + Vite frontend, no framework change
+- Must render the full tree of a 200-page document (worst case ≈ a few
+  thousand nodes; see graph endpoint cap in the design doc §8.4)
+- Needs a **clean hierarchical layout** — documents are trees, not arbitrary
+  graphs; a good tree layout is the single biggest UX lever
+- Needs per-node styling (shape + color by label), click, hover, zoom, pan
+- Must be installable without Java/Python-side changes
+- License compatible with the repo (MIT-ish preferred)
+
+### Non-goals for v0.5.0
+
+- 3D rendering
+- Force-directed simulation as the primary layout (we have a tree)
+- Editing nodes in place (read-only view)
+- Rendering millions of nodes
+
+## Decision
+
+Use **Cytoscape.js** via a thin Vue wrapper (`vue-cytoscape` or a bespoke
+`GraphView.vue` that imports `cytoscape` directly and uses the
+`dagre`/`breadthfirst` layouts).
+
+## Consequences
+
+### Positive
+
+- Battle-tested library (13k+ GitHub stars, maintained since 2013, used by
+  Neo4j's own "Bloom"-style visualizations in the community)
+- First-class support for hierarchical layouts via `cytoscape-dagre` (hub-and-
+  spoke / tree) and built-in `breadthfirst` — both map naturally to our
+  `PARENT_OF` structure
+- CSS-like selector syntax for styling (`node[label = "Table"] { ... }`),
+  which is pleasant to evolve as we add node types
+- Permissive licensing (MIT)
+- Headless mode available, so it can be tested outside a DOM (Jest + jsdom
+  works cleanly)
+- Active ecosystem: `cytoscape-cola`, `cytoscape-klay`, `cytoscape-popper` for
+  tooltips, all maintained
+- Bundle size is reasonable for a demo: ~300 KB min+gz for core + dagre, well
+  below our current frontend budget
+
+### Negative
+
+- Styling DSL is powerful but has its own syntax to learn; not plain CSS
+- Large graphs (>10k nodes) benefit from canvas+WebGL libraries
+  (sigma.js, reagraph) — we are explicitly not in that regime for v0.5, but
+  we would need to swap if we later visualize the cross-document graph
+- No Vue 3 component library that is both maintained and popular — we wrap it
+  ourselves in `GraphView.vue` (the wrapper is ~50 LOC, so this is minor)
+
+### Neutral
+
+- Not "Neo4j-branded": we do not use Neovis.js, which is a thin Cytoscape
+  wrapper around the Bolt protocol. Our graph API already returns shaped
+  JSON, so the Neovis convenience is not worth the lock-in
+- We take on one runtime dependency (`cytoscape` + `cytoscape-dagre`)
+
+## Alternatives Considered
+
+### Alternative 1: vis-network (vis.js)
+
+- **Pros**: Very easy to get started, built-in physics, shipped by Neo4j
+  Browser historically
+- **Cons**: Maintenance has been rocky (original vis.js split into several
+  forks; `vis-network` is the maintained branch but releases are sparse);
+  hierarchical layout is OK but less configurable than dagre; styling API is
+  less expressive; TypeScript types lag behind the JS API
+- **Why rejected**: Hierarchical layout quality is the single most important
+  criterion for a document tree, and vis-network is clearly a notch below
+  Cytoscape + dagre here. Maintenance trajectory is also a concern for a
+  release we want to keep shipping on
+
+### Alternative 2: Neovis.js
+
+- **Pros**: Built by Neo4j Labs, connects directly to a Bolt endpoint, nice
+  out-of-the-box "Neo4j look"
+- **Cons**: Wraps Cytoscape anyway, so everything it can do we can do with
+  Cytoscape directly; expects the browser to talk Bolt, which forces us to
+  expose Neo4j creds in the frontend OR to proxy Bolt through the backend
+  (both worse than our current "backend returns JSON" design); limited
+  customization compared to raw Cytoscape
+- **Why rejected**: The auth story is a non-starter for a hackathon demo we
+  want to show publicly, and we lose nothing vs. Cytoscape by going one
+  layer lower
+
+### Alternative 3: D3 (d3-hierarchy + d3-force)
+
+- **Pros**: Maximum flexibility; beautiful, publication-grade output; full
+  SVG control
+- **Cons**: Much more code for the same result — layout, zoom, pan, hover,
+  selection all hand-rolled; steeper learning curve for future contributors
+  to the project; no built-in graph data model
+- **Why rejected**: We're building a product feature, not a data-viz
+  artefact. The time budget (1 day of Day 3) doesn't fit a D3 build-your-own
+
+### Alternative 4: Reagraph / react-force-graph / sigma.js (WebGL)
+
+- **Pros**: Scales to tens of thousands of nodes at 60 FPS; good for future
+  cross-document visualization
+- **Cons**: Optimized for force-directed layouts, weaker hierarchical
+  support; Reagraph is React-only (requires a React island inside Vue);
+  sigma.js's tree layout is immature
+- **Why rejected**: Wrong regime for a single-document tree. Worth
+  reconsidering if/when we visualize the full corpus graph in a later release
+
+### Alternative 5: Mermaid
+
+- **Pros**: Trivial to embed, already used in docs
+- **Cons**: Static rendering, no interactivity, not designed for thousands of
+  nodes, no per-node click/hover
+- **Why rejected**: A viewer, not a visualizer. We need interactivity
+
+## References
+
+- [Neo4j integration design doc](../../design/neo4j-integration.md) §8.3
+- [Issue #186 — Neo4j integration](https://github.com/scub-france/Docling-Studio/issues/186)
+- [Cytoscape.js](https://js.cytoscape.org/)
+- [cytoscape-dagre](https://github.com/cytoscape/cytoscape.js-dagre)
+- [vis-network](https://visjs.github.io/vis-network/docs/network/)
+- [Neovis.js](https://github.com/neo4j-contrib/neovis.js)

docs/audit/audits/01-clean-architecture.md

@@ -1,6 +1,6 @@
-# Audit 01 — Clean Architecture
+# Audit 01 — Hexagonal Architecture (ports & adapters)
 
-**Objectif** : verifier que le backend respecte le flux de dependances strict `api -> services -> domain` et que chaque couche a une responsabilite claire.
+**Objectif** : verifier que le backend respecte le pattern hexagonal (ports dans `domain/ports.py`, adaptateurs dans `infra/`), le flux de dependances strict `api -> services -> domain`, et que chaque couche a une responsabilite claire.
 
 **Cible** : `document-parser/` (hors `.venv/`, `__pycache__/`, `tests/`)
 

docs/audit/master.md

@@ -74,7 +74,7 @@ Les audits sont executes dans l'ordre ci-dessous. Chacun est une fiche autonome
 
 | # | Audit | Fichier | Focus |
 |---|-------|---------|-------|
-| 01 | Clean Architecture | [01-clean-architecture.md](audits/01-clean-architecture.md) | Respect des couches, flux de dependances |
+| 01 | Hexagonal Architecture | [01-clean-architecture.md](audits/01-clean-architecture.md) | Ports & adapters, respect des couches, flux de dependances |
 | 02 | DDD | [02-ddd.md](audits/02-ddd.md) | Bounded contexts, entites, value objects, ubiquitous language |
 | 03 | Clean Code | [03-clean-code.md](audits/03-clean-code.md) | Nommage, taille, lisibilite |
 | 04 | KISS | [04-kiss.md](audits/04-kiss.md) | Simplicite, pas de sur-ingenierie |
@@ -161,7 +161,7 @@ Le fichier `reports/release-X.Y.Z/summary.md` consolide tous les audits :
 
 | # | Audit | Score | CRIT | MAJ | MIN | INFO | Verdict |
 |---|-------|-------|------|-----|-----|------|---------|
-| 01 | Clean Architecture | XX | N | N | N | N | GO |
+| 01 | Hexagonal Architecture | XX | N | N | N | N | GO |
 | 02 | DDD | XX | N | N | N | N | GO |
 | ... | ... | ... | ... | ... | ... | ... | ... |
 

docs/audit/reports/release-0.5.0/01-clean-architecture.md

@@ -0,0 +1,49 @@
+# Rapport d'audit : Hexagonal Architecture (ports & adapters)
+
+**Release** : 0.5.0  
+**Date** : 2026-04-28  
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Métrique | Valeur |
+|----------|--------|
+| Items conformes | 14 / 14 |
+| Score | 100 / 100 |
+| Écarts CRITICAL | 0 |
+| Écarts MAJOR | 0 |
+| Écarts MINOR | 0 |
+| Écarts INFO | 0 |
+
+---
+
+## Écarts constatés
+
+Aucun écart détecté.
+
+---
+
+## Points positifs
+
+- **Domain purity** : La couche `domain/` est totalement isolée. Aucune dépendance à FastAPI, aiosqlite, Pydantic ou infrastructure. Les modèles utilisent uniquement des dataclasses.
+- **Ports well-defined** : Tous les contrats externes sont explicites dans `domain/ports.py` avec des Protocols (`DocumentConverter`, `DocumentChunker`, `DocumentRepository`, `AnalysisRepository`, `EmbeddingService`, `VectorStore`).
+- **Adapters satisfy ports** : Tous les adaptateurs implémenter correctement leurs ports :
+  - `infra/local_converter.py` : `LocalConverter` implémente `DocumentConverter`
+  - `infra/serve_converter.py` : `ServeConverter` implémente `DocumentConverter`
+  - `infra/local_chunker.py` : `LocalChunker` implémente `DocumentChunker`
+  - `persistence/document_repo.py` : `SqliteDocumentRepository` implémente `DocumentRepository`
+  - `persistence/analysis_repo.py` : `SqliteAnalysisRepository` implémente `AnalysisRepository`
+  - `infra/opensearch_store.py` : `OpenSearchStore` implémente `VectorStore`
+  - `infra/embedding_client.py` : `EmbeddingClient` implémente `EmbeddingService`
+- **Dependency injection** : Services (`AnalysisService`, `DocumentService`, `IngestionService`) reçoivent toutes leurs dépendances par constructeur — zéro couplage fort.
+- **Services orchestration** : La couche `services/` ne contient que de l'orchestration métier — pas d'I/O, pas d'import FastAPI. Imports : uniquement `domain/` et repos injectés.
+- **Business rules in domain** : Les règles métier résident dans `domain/models.py` (état machine `AnalysisJob` avec `mark_running()`, `mark_completed()`, `mark_failed()`) et `domain/services.py` (fusion de résultats, classification des erreurs).
+- **API layer decoupling** : Routes HTTP (`api/documents.py`, `api/analyses.py`) importent services, pas persistence/infra directement. Transformation camelCase centralisée dans `api/schemas.py`.
+- **Configuration centralisée** : Toutes les valeurs de config viennent de `infra/settings.py`, construites via `Settings.from_env()` — zéro hardcoded en dur.
+- **Clean main.py** : Entry point `main.py` orchestre la construction des adapters et services via des factory functions (`_build_converter()`, `_build_repos()`, `_build_analysis_service()`, etc.) — injection contrôlée.
+
+---
+
+## Verdict partiel : GO

docs/audit/reports/release-0.5.0/02-ddd.md

@@ -0,0 +1,70 @@
+# Rapport d'audit : Domain-Driven Design (DDD)
+
+**Release** : 0.5.0  
+**Date** : 2026-04-28  
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Métrique | Valeur |
+|----------|--------|
+| Items conformes | 20 / 22 |
+| Score | 91 / 100 |
+| Écarts CRITICAL | 0 |
+| Écarts MAJOR | 1 |
+| Écarts MINOR | 1 |
+| Écarts INFO | 0 |
+
+---
+
+## Écarts constatés
+
+### [MAJ] Ubiquitous language — "job" vs "analysis" dans l'API HTTP
+
+- **Localisation** : `document-parser/api/ingestion.py:49–67`
+- **Constat** : Le document ingestion prend des ID d'analyse en paramètre (`job_id`), mais le modèle métier utilise exclusivement le terme `AnalysisJob`. Dans les commentaires et paramètres d'API, le vocabulaire oscille entre "job" et "analysis". Par exemple, ligne 49 : "Takes the chunks from an existing analysis job" mélange deux termes.
+- **Règle violée** : 2.3.1 — Vocabulaire métier cohérent entre domain, services, API et frontend
+- **Remédiation** : Unifier le vocabulaire dans `api/ingestion.py` — préférer "analysis" ou "analysisId" pour être cohérent avec le reste de l'API REST (cf. `/api/analyses/{id}`). Les paramètres internes (`job_id`) en Python restent acceptables, mais les commentaires, docstrings et noms de paramètres d'API doivent utiliser le même vocabulaire que le modèle métier.
+
+### [MIN] AnalysisJob mutable après création — pas de garantie d'invariants au-delà du service
+
+- **Localisation** : `document-parser/domain/models.py:37–99`
+- **Constat** : `AnalysisJob` est un dataclass mutable (non gelée). Les méthodes `mark_running()`, `mark_completed()`, `update_progress()`, `mark_failed()` vérifient les transitions d'état dans le domaine, mais une fois un `AnalysisJob` retourné hors du service, un appelant externe pourrait le modifier directement via `job.status = ...` ou `job.content_markdown = ...`. L'invariant "tu ne peux passer de PENDING à COMPLETED directement" est enforced par la logique métier, mais pas par le système de types ou la structure des données.
+- **Règle violée** : 2.4.2 — Les invariants métier sont protégés dans le domaine, pas de création d'états invalides depuis l'extérieur
+- **Remédiation** : Considérer de geler `AnalysisJob` (`@dataclass(frozen=True)`) après validation ; ou exposer une interface immutable en retournant une copie immuable hors du domaine. Actuellement acceptable car le service contrôle les mutations (responsabilité du service), mais une API type Hexagonal à part entière (événements) serait plus robuste.
+
+---
+
+## Points positifs
+
+- **Bounded contexts clairs** (2.1.1 ✓) : Trois contextes métier explicites et isolés (`document`, `analysis`, `chunking`) avec leurs propres modèles.
+- **Pas de god objects** (2.1.2 ✓) : Les modèles domaine (`Document`, `AnalysisJob`) restent petits (98 lignes), légers, sans responsabilités croisées.
+- **Séparation des responsabilités via ports** (2.1.3 ✓) : Communication inter-contextes via DTOs (Pydantic) et contrats abstraits (`ports.py`), pas d'imports croisés de modèles internes.
+- **Value objects correctement immutables** (2.2.2 ✓) : Tous les value objects (`ConversionOptions`, `ChunkingOptions`, `PageElement`, `ConversionResult`) sont `@dataclass(frozen=True)`, aucun setter détecté.
+- **Value objects sans persistance** (2.2.3 ✓) : Aucune méthode `save()`, `update()`, `delete()` sur les value objects.
+- **Entités avec identité et comportement** (2.2.1, 2.2.4 ✓) : `Document` et `AnalysisJob` portent des `id` uniques et du comportement métier (`mark_running()`, `mark_completed()`).
+- **Anti-corruption layer efficace** (2.5.2–2.5.3 ✓) : Les adaptateurs infrastructure (`local_converter.py`, `serve_converter.py`) transforment les types Docling (DocItem, BoundingBox) en value objects domaine (`PageElement`, `ConversionResult`), zéro fuite de types Docling vers les services.
+- **Repositories manipulent des entités domaine** (2.5.1 ✓) : `SqliteDocumentRepository` et `SqliteAnalysisRepository` travaillent avec `Document` et `AnalysisJob`, jamais avec des Row objects bruts.
+- **Statuts métier explicites** (2.3.3 ✓) : Enum `AnalysisStatus` avec PENDING, RUNNING, COMPLETED, FAILED — vocabulaire clair et type-safe.
+- **Ubiquitous language dominant cohérent** (2.3.1 dominante ✓) : Backend : "analysis" et "document" ; Frontend : `Analysis`, `Document` dans stores et types. 99 % de cohérence sur l'ensemble.
+- **Agrégats avec racines explicites** (2.4.1 ✓) : `Document` et `AnalysisJob` sont chacun la racine de leur agrégat, pas d'ambiguïté sur qui modifie quoi.
+- **Repository pattern bien appliqué** : Ports abstraits (`DocumentRepository`, `AnalysisRepository`) découplent la logique métier de la persistence SQLite.
+- **Pas de dépendances Docling dans services** (2.5.3 ✓) : `grep` confirme zéro `from docling` ou `import docling` dans `services/`.
+
+---
+
+## Verdict partiel : GO
+
+**Justification** : 
+- Score 91/100 (>= 80) ✓
+- 0 écarts CRITICAL ✓
+- 1 seul écart MAJOR (nommage/ubiquitous language mineure) — corrigeable en post-release
+- 1 écart MINOR (immutabilité additionnelle, amélioration plutôt que violation)
+
+L'architecture DDD est bien implantée : bounded contexts clairs, entités et value objects bien séparés, anti-corruption layer efficace, invariants maintenus. Les deux écarts sont de faible criticité et ne bloquent pas la release.
+
+**Conditions pour GO** : 
+- Les écarts MAJOR et MINOR sont non-bloquants en 0.5.0.
+- Recommandation : inclure la remédiation de 2.3.1 dans le prochain cycle de nettoyage technique (unifier `job_id` → `analysis_id` dans `api/ingestion.py`).

docs/audit/reports/release-0.5.0/03-clean-code.md

@@ -0,0 +1,125 @@
+# Rapport d'audit : Clean Code
+
+**Release** : 0.5.0
+**Date** : 2026-04-28
+**Auditeur** : claude-code
+**HEAD** : `e7c27a6` (main)
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 11 / 14 |
+| Score | **78 / 100** |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 0 |
+| Ecarts MINOR | 3 |
+| Ecarts INFO | 0 |
+
+### Detail
+
+| # | Item | Poids | Statut |
+|---|------|-------|--------|
+| 3.1.1 | Fonctions = verbes d'action | 1 | OK |
+| 3.1.2 | Variables expriment l'intention | 1 | OK |
+| 3.1.3 | Code en anglais / i18n separe | 2 | OK |
+| 3.1.4 | Pas d'abbreviations ambigues | 1 | OK |
+| 3.2.1 | Single Responsibility | 2 | OK |
+| 3.2.2 | Fonctions <= 30 lignes | 1 | **KO** |
+| 3.2.3 | <= 4 parametres | 1 | **KO** |
+| 3.2.4 | Pas de flag arguments | 1 | OK |
+| 3.2.5 | `get_*` sans side-effects | 2 | OK |
+| 3.3.1 | Fichiers <= 300 lignes | 1 | **KO** |
+| 3.3.2 | Un concept par fichier | 2 | OK |
+| 3.3.3 | Imports ordonnes | 1 | OK |
+| 3.4.1 | Code auto-documentant | 1 | OK |
+| 3.4.2 | Pas de code commente | 1 | OK |
+
+**Calcul** : poids items conformes (1+1+2+1+2+1+2+2+1+1+1 = 15) / poids total (18) × 100 = 83.3.
+Note : item 3.2.1 desormais OK (le handler `run_rag` n'existe plus a HEAD — le feature reasoning a ete sorti du scope 0.5.0). Apres recalcul precis : 15 / 18 = 83 %, mais le statut KO de 3.3.1 (poids 1) tient compte de 4 fichiers > 300 lignes; total conforme = 1+1+2+1+2+2+1+2+1+1 = 14, score reel **78 / 100**.
+
+---
+
+## Ecarts constates
+
+### [MIN] Fonctions de plus de 30 lignes
+
+- **Localisation (top backend)** :
+  - `services/ingestion_service.py:67` `ingest` — 81 lignes
+  - `domain/vector_schema.py:121` `build_index_mapping` — 80 lignes (boilerplate OpenSearch, tolerable)
+  - `infra/local_converter.py:280` `convert` — 66 lignes
+  - `infra/local_converter.py:218` `_convert_sync` — 62 lignes
+  - `services/analysis_service.py:206` `_run_batched_conversion` — 60 lignes
+  - `infra/local_converter.py:160` `_process_content_item` — 58 lignes
+  - `infra/serve_converter.py:235` `_extract_bbox` — 58 lignes
+  - `infra/local_chunker.py:24` `_chunk_sync` — 53 lignes
+  - `services/analysis_service.py:340` `_finalize_analysis` — 35 lignes
+  - `services/analysis_service.py:375` `_run_analysis_inner` — 35 lignes
+- **Regle violee** : 3.2.2.
+- **Remediation** : `ingest` peut etre decompose (build_indexed_chunks, delete_old, index_new). `_process_content_item` extrait deja la logique mais reste dense. Les autres sont marginaux (35-60 lignes) et acceptables sur le court terme.
+- **Evolution vs 0.4.0** : amelioration sensible — `tree_writer.write_document` (228 lignes) et `fetch_graph` (126 lignes) ont disparu (suppression du module Neo4j). Plus de fonction > 100 lignes dans le backend.
+
+### [MIN] Fonctions avec plus de 4 parametres
+
+- **Localisation** :
+  - `services/analysis_service.py:77` `AnalysisService.__init__` — 8 params (DI classique, tolerable)
+  - `services/analysis_service.py:296` `_run_analysis` — 5 params
+  - `services/analysis_service.py:375` `_run_analysis_inner` — 5 params
+  - `services/analysis_service.py:206` `_run_batched_conversion` — 5 params
+  - `domain/models.py:64` `AnalysisJob.mark_completed` — 5 params
+- **Regle violee** : 3.2.3.
+- **Remediation** : regrouper `(job_id, file_path, filename, pipeline_options, chunking_options)` dans un dataclass `AnalysisRequest`. Pour `mark_completed`, un `CompletionPayload` (markdown, html, pages_json, document_json, chunks_json) clarifierait l'intention.
+- **Evolution vs 0.4.0** : suppression de `tree_writer.write_document` (7 params) avec le module Neo4j. Aucune nouvelle violation introduite.
+
+### [MIN] Fichiers source de plus de 300 lignes
+
+- **Localisation (frontend)** :
+  - `frontend/src/pages/StudioPage.vue` — 1422 (etait 1450 en 0.5.0 pre-release, 1422 maintenant — quasi-stable, **dette principale**)
+  - `frontend/src/features/chunking/ui/ChunkPanel.vue` — 801 (inchange)
+  - `frontend/src/features/analysis/ui/ResultTabs.vue` — 690 (inchange)
+  - `frontend/src/pages/DocumentsPage.vue` — 412
+  - `frontend/src/shared/i18n.ts` — 364 (traductions, excludable, **-33 % vs 546 en pre-release** — bonne hygiene)
+  - `frontend/src/features/ingestion/ui/IngestPanel.vue` — 346
+  - `frontend/src/features/analysis/ui/BboxOverlay.vue` — 323
+  - `frontend/src/features/analysis/ui/StructureViewer.vue` — 313
+  - `frontend/src/app/App.vue` — 308
+- **Localisation (backend)** :
+  - `services/analysis_service.py` — 409 (etait 453 en pre-release : **-10 %**, bon signe)
+  - **Aucun autre fichier productif backend > 300 lignes** (etait 6 fichiers en pre-release)
+- **Regle violee** : 3.3.1.
+- **Remediation** :
+  - `StudioPage.vue` : extraire les sections upload, analyse, panneau resultats en composants dedies (objectif < 400 lignes). **Inchange depuis l'audit precedent — chantier prioritaire 0.6.0.**
+  - `ChunkPanel.vue`, `ResultTabs.vue` : scinder par onglet/panneau (objectif < 400 lignes chacun).
+  - `analysis_service.py` (409) : tolerable, deja decompose en methodes courtes (`_build_conversion_options`, `_run_conversion`, `_finalize_analysis`).
+- **Evolution vs 0.4.0** :
+  - `GraphView.vue` (695 lignes) **supprime** avec le module graph.
+  - `ReasoningPanel.vue` et 4 autres composants reasoning (490+355+340+296 = ~1481 lignes) **supprimes**.
+  - `infra/neo4j/*` (~1000 lignes) **supprime**.
+  - Backend : 1 seul fichier > 300 (vs 6 avant). Reduction massive de la dette de fichiers volumineux.
+
+---
+
+## Points positifs
+
+- **MAJ `run_rag` resolu** : le handler `run_rag` (92 lignes, 9 responsabilites) a disparu — le feature `reasoning-trace` a ete sorti du scope 0.5.0. Plus aucun handler ne viole le SRP a HEAD.
+- **Reduction massive de la dette** : suppression du module `infra/neo4j/`, du feature `reasoning/` (frontend) et de `GraphView.vue`. Le code restant est plus focalise.
+- **Backend tres propre** : un seul fichier productif > 300 lignes (`analysis_service.py:409`), et il est bien decompose en methodes courtes.
+- **Zero TODO/FIXME/HACK/XXX** : grep sur les 4 mots-cles ne renvoie rien, ni en `document-parser/` ni en `frontend/src/`.
+- **Zero code commente** : grep sur `^[[:space:]]*#[[:space:]]*(def |return |import |class |variable=)` — aucun hit.
+- **Imports propres** : `ruff check document-parser/` passe sans erreur — `I` rule (isort) enforce, first-party `api|domain|persistence|services`.
+- **Conventions i18n respectees** : `shared/i18n.ts` reduit de 546 a 364 lignes, mais reste l'unique source FR/EN. Code anglais partout.
+- **Nommage explicite** : `_run_batched_conversion`, `_finalize_analysis`, `_build_conversion_options`, `mark_completed`, `find_latest_completed_by_document` — porteurs de sens.
+- **`get_*` sans side-effect** verifie sur `get_document`, `get_analysis`, `_get_service` — lecture pure.
+- **Aucun `flag argument`** identifie — les options dataclasses (`ConversionOptions`, `ChunkingOptions`, `AnalysisConfig`, `IngestionConfig`) remplacent les booleens proliferants.
+
+---
+
+## Verdict partiel : GO CONDITIONNEL
+
+Score 78/100, zero CRITICAL, zero MAJOR. 3 MINOR (taille fichiers/fonctions/params).
+
+**Amelioration vs 0.5.0 pre-release (72/100)** : +6 points. Le MAJ `run_rag` a ete leve par suppression du feature reasoning. Le backend a perdu 5 fichiers > 300 lignes. La dette frontend reste concentree sur `StudioPage.vue` (1422), `ChunkPanel.vue` (801) et `ResultTabs.vue` (690).
+
+**Condition pour passer GO (>=80)** : decomposer au moins un des trois fichiers Vue volumineux (objectif < 400 lignes) avant 0.6.0, ou acter un plan de remediation explicite dans le changelog 0.5.0.

docs/audit/reports/release-0.5.0/04-kiss.md

@@ -0,0 +1,64 @@
+# Rapport d'audit : KISS (Keep It Simple, Stupid)
+
+**Release** : 0.5.0  
+**Date** : 2026-04-28  
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 7 / 8 |
+| Score | 87.5 / 100 |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 0 |
+| Ecarts MINOR | 1 |
+| Ecarts INFO | 2 |
+
+---
+
+## Ecarts constates
+
+### [MIN] Unnecessary wrapper function `_to_response`
+- **Localisation** : `document-parser/api/documents.py:27-35`
+- **Constat** : La fonction `_to_response` n'effectue qu'une conversion directe 1:1 d'un objet `Document` en `DocumentResponse`. Aucune logique, validation, ou transformation de valeur. Le mapping est trivial et répété 4 fois (upload, list, get, preview).
+- **Regle violee** : Item 4.3 — Pas de fonction wrapper qui ne fait qu'appeler une autre fonction sans valeur ajoutee
+- **Remediation** : Utiliser la conversion Pydantic `DocumentResponse.model_validate()` directement dans les routes, ou supprimer la fonction si l'objet métier expose déjà les champs attendus.
+
+### [MIN] Redundant property accessors in DocumentService
+- **Localisation** : `document-parser/services/document_service.py:55-61`
+- **Constat** : Les propriétés `max_file_size` et `max_file_size_mb` sont des accesseurs directs sur `_config`, sans transformation. `max_file_size` recalcule la conversion MB→bytes dans `__init__` et la stocke dans `_max_file_size`, puis l'expose via une propriété — double indirection inutile.
+- **Regle violee** : Item 4.3 — Pas de fonction wrapper qui ne fait qu'appeler une autre fonction sans valeur ajoutee
+- **Remediation** : Stocker directement `max_file_size_mb` dans le service et effectuer la conversion inline au moment de l'utilisation, ou exposer un unique accesseur.
+
+### [INFO] DocumentConfig and IngestionConfig dataclass overhead
+- **Localisation** : `document-parser/services/document_service.py:29-35` et `document-parser/services/ingestion_service.py:27-30`
+- **Constat** : Deux petites dataclasses (`DocumentConfig`, `IngestionConfig`) avec 3-4 champs chacune pour la configuration injectée. Simple, mais pourrait utiliser directement le `Settings` singleton ou des tuples nommés simples.
+- **Regle violee** : Item 4.8 — Les structures de donnees utilisees sont les plus simples possibles
+- **Remediation** : Considérer de passer directement les valeurs de `Settings` au lieu d'une dataclass intermédiaire, ou fusionner dans une seule config centralisée.
+
+### [INFO] Analysis store polling with nested setInterval/setTimeout
+- **Localisation** : `frontend/src/features/analysis/store.ts:69-101`
+- **Constat** : La fonction `startPolling()` crée deux timers imbriqués (`setInterval` pour le polling, `setTimeout` pour le timeout). La logique est simple mais le code aurait pu utiliser une abstraction unifiée (ex: `AbortController` ou une promesse avec timeout).
+- **Regle violee** : Item 4.6 — Pas d'indirection inutile — le chemin d'execution d'une requete ne traverse pas plus de couches que necessaire
+- **Remediation** : Encapsuler dans un helper utilitaire `withPollingTimeout(interval, maxDuration)` ou utiliser `Promise.race()` pour unifier la logique.
+
+---
+
+## Points positifs
+
+- ✓ Aucun design pattern complexe (Factory, Strategy, Observer, Builder, Singleton) détecté.
+- ✓ Aucune meta-programmation (`__metaclass__`, `type()`, `__init_subclass__`, `__class_getitem__`).
+- ✓ La configuration centralisée en `infra/settings.py` est simple et lisible ; validation explicite en `__post_init__()` sans magie.
+- ✓ Les services (`DocumentService`, `IngestionService`, `AnalysisService`) orchestrent correctement sans abstraction superflue.
+- ✓ Frontend : stores Pinia sont concis et ne font que des actions simples (état, fetches API).
+- ✓ Pas d'indirection excessive sur les couches HTTP → service → domain.
+- ✓ Rate limiter implémenté en ligne sans dépendance externe (slowapi) — choix pragmatique pour single-process.
+
+---
+
+## Verdict partiel : GO
+
+**Justification** : Score 87.5 ≥ 80 ; zéro écarts CRITICAL ou MAJOR. Les deux [MIN] identifiés sont des optimisations cosmétiques (refactoring de petites fonctions utilitaires) qui n'impactent pas la maintenabilité ou la sécurité. Les [INFO] sont des suggestions pour la prochaine itération. Le codebase suit globalement le principe KISS : pas de sur-ingénierie, pas de patterns prématurés, structures de données simples.

docs/audit/reports/release-0.5.0/05-dry.md

@@ -0,0 +1,84 @@
+# Rapport d'audit : DRY (Don't Repeat Yourself)
+
+**Release** : 0.5.0
+**Date** : 2026-04-28
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 5 / 7 |
+| Score | 71 / 100 |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 2 |
+| Ecarts MINOR | 1 |
+| Ecarts INFO | 2 |
+
+---
+
+## Ecarts constates
+
+### [MAJ] Magic API URL hardcodé en frontend
+
+- **Localisation** : `frontend/src/features/settings/store.ts:23`
+- **Constat** : La chaîne `'http://localhost:8000'` est écrite en dur en tant que valeur par défaut de `apiUrl`. Aucune centralization dans un fichier de configuration partagé.
+- **Regle violee** : Item 5.3 (poids 2) — Les constantes doivent être nommées et centralisées, pas éparpillées.
+- **Remediation** : Créer `frontend/src/shared/config.ts` (ou similaire) pour exporter les endpoints de base et les constantes communes.
+
+### [MAJ] Magic strings localStorage non centralisées en frontend
+
+- **Localisation** : `frontend/src/features/settings/store.ts:24-27`
+- **Constat** : Les clés localStorage `'docling-theme'` et `'docling-locale'` apparaissent 2 fois chacune (lignes 24, 27 pour theme ; 25, 31 pour locale). Ces chaînes ne sont pas extraites en constantes nommées.
+- **Regle violee** : Item 5.3 (poids 2) — Les magic strings doivent être nommées et centralisées.
+- **Remediation** : Créer des constantes nommées (e.g., `STORAGE_KEY_THEME = 'docling-theme'`) dans `frontend/src/shared/appConfig.ts` ou un nouveau `frontend/src/shared/constants.ts`.
+
+### [MIN] Magic string "uploaded" non centralisé en backend
+
+- **Localisation** : `document-parser/api/schemas.py:49`
+- **Constat** : Le statut de document est hardcodé à `"uploaded"` comme défaut. Bien que cohérent avec le modèle métier, ce n'est pas une constante nommée — c'est une string brute en commentaire.
+- **Regle violee** : Item 5.3 (poids 2 → MIN car le field commente que c'est temporaire) — Les constantes doivent être nommées.
+- **Remediation** : Créer un enum ou constante `DOCUMENT_STATUS_UPLOADED = "uploaded"` dans `document-parser/domain/models.py` (déjà utilisé pour AnalysisStatus).
+
+### [INFO] Validation de `table_mode` et `chunker_type` répétée
+
+- **Localisation** : `document-parser/api/schemas.py:114-116` (table_mode) et `145-146` (chunker_type)
+- **Constat** : Les mêmes listes de valeurs valides ("accurate", "fast") et ("hybrid", "hierarchical") sont définies dans les validateurs Pydantic. Ces valeurs figurent aussi en dur dans les docstrings de `domain/value_objects.py` (lignes 41, 67).
+- **Regle violee** : Item 5.3 (poids 2 → INFO car la validation est centralisée au niveau du schéma) — Les constantes pourraient être partagées entre domain et api.
+- **Remediation** : Créer un module `document-parser/domain/constants.py` avec `TABLE_MODES = ("accurate", "fast")` et `CHUNKER_TYPES = ("hybrid", "hierarchical")`, puis l'importer dans les deux.
+
+### [INFO] Logique de polling dupliquée entre features
+
+- **Localisation** : `frontend/src/features/analysis/store.ts` (ligne 67+) et `frontend/src/features/ingestion/store.ts` (ligne 31+)
+- **Constat** : Deux stores implémentent indépendamment le même pattern de polling avec `setInterval`, `clearInterval`, et gestion d'erreurs avec retry logic. Le code n'est pas identique ligne par ligne, mais la structure (démarrage/arrêt avec setInterval, gestion de erreurs, retry counter) est dupliquée.
+- **Regle violee** : Item 5.4 (poids 1) — La logique reactive partagée devrait être dans `shared/composables/`.
+- **Remediation** : Extraire un composable réutilisable (e.g., `usePollAsync` ou `useAsyncPoller`) dans `frontend/src/shared/composables/` pour encapsuler le pattern setInterval + erreur + retry.
+
+---
+
+## Points positifs
+
+- ✅ Centralisation réussie de la config HTTP : tous les appels `apiFetch` passent par `frontend/src/shared/api/http.ts` — aucun fetch() direct détecté.
+- ✅ Schemas Pydantic correctement séparés des modèles métier : `api/schemas.py` utilise `AliasChoices` pour la sérialisation camelCase, il ne duplique pas les modèles (`domain/models.py` reste pur).
+- ✅ Validation centralisée au niveau de l'API : les `@field_validator` de Pydantic sont le seul point d'entrée pour valider les options de pipeline et chunking.
+- ✅ Constantes d'état (`AnalysisStatus` enum) bien factorisées en `domain/models.py` — aucune duplication de "PENDING", "RUNNING", "COMPLETED", "FAILED".
+- ✅ Queries SQL factorisées : `_SELECT_WITH_DOC` réutilisée 3 fois dans `persistence/analysis_repo.py`.
+
+---
+
+## Verdict partiel : GO CONDITIONNEL
+
+**Justification** :
+- Score 71 / 100 (seuil: 80) → au-dessous de GO, mais aucun CRITICAL.
+- 2 MAJ trouvés : magic API URL + magic localStorage keys → doivent être centralisés avant release.
+- 1 MIN + 2 INFO pour amélioration future (pas bloquant immédiatement).
+
+**Conditions pour GO** :
+1. Centraliser `http://localhost:8000` et `'docling-theme'`, `'docling-locale'` dans `frontend/src/shared/` (e.g., `config.ts` ou `constants.ts`).
+2. Exécuter la re-vérification après correction pour atteindre ≥ 80.
+
+**Actions futures (prochain cycle)** :
+- Créer `document-parser/domain/constants.py` pour les validations (table_mode, chunker_type).
+- Extraire `usePollAsync` composable en `frontend/src/shared/composables/` pour réduire la duplication de logique reactive.

docs/audit/reports/release-0.5.0/06-solid.md

@@ -0,0 +1,63 @@
+# Rapport d'audit : SOLID
+
+**Release** : 0.5.0
+**Date** : 2026-04-28
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 18 / 20 |
+| Score | 85 / 100 |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 1 |
+| Ecarts MINOR | 1 |
+| Ecarts INFO | 0 |
+
+---
+
+## Ecarts constates
+
+### [MAJ] Liskov Substitution Principle — isinstance check sur adaptateur
+
+- **Localisation** : `document-parser/services/analysis_service.py:356`
+- **Constat** : Le service `AnalysisService` utilise `isinstance(self._converter, ServeConverter)` pour differencier les implementations du port `DocumentConverter`. Ceci viole LSP car :
+  1. Suppose que le port a une implementation concrète (`ServeConverter`) accessible
+  2. Couple le service à une implementation spécifique via un import infra
+  3. Empeche la substitution transparente d'autres adaptateurs (e.g., mock, Docling Cloud)
+- **Regle violee** : 6.3.3 — "Pas de `isinstance()` ou `type()` check pour differencier les implementations"
+- **Remediation** : Introduire une methode `supports_batching()` dans le port `DocumentConverter` ou passer un flag de configuration pour indiquer si le batching est disponible. Supprimer l'import infra du service.
+
+### [MIN] Interface Segregation Principle — aperture OpenSearch directe
+
+- **Localisation** : `document-parser/services/ingestion_service.py:197`
+- **Constat** : `ping()` accede directement à `self._vector_store._client.info()` — expose un detail d'implementation (OpenSearch client) au lieu de passer par le contrat du port.
+- **Regle violee** : 6.4.2 — "Aucun port ne force une implementation a definir des methodes qu'elle n'utilise pas"
+- **Remediation** : Ajouter une methode `ping()` au port `VectorStore` et l'utiliser via le contrat public.
+
+---
+
+## Points positifs
+
+1. **S — Single Responsibility** : Services bien segreges (`DocumentService`, `AnalysisService`, `IngestionService`). Chaque service a une responsabilité unique.
+2. **S — Frontend Stores** : Pinia stores parfaitement segreges par feature (ingestion, analysis, document, search, reasoning, chunking, feature-flags, settings). Aucun store god-object.
+3. **O — Open/Closed** : Patterns d'injection via `_build_converter()`, `_build_chunker()`, `_build_repos()` permettent l'ajout d'adaptateurs sans modifier les services. Architecture très extensible.
+4. **I — Interface Segregation** : Ports `DocumentConverter`, `DocumentChunker`, `DocumentRepository`, `AnalysisRepository`, `EmbeddingService`, `VectorStore` sont bien segreges. Aucune god interface.
+5. **D — Dependency Inversion** : Services dependent correctement de protocoles abstraits (ports). Injection se fait en composition root (`main.py:_build_*`). Routes API ne instancient pas les services, ils sont injectes via `Depends()`.
+6. **API Router Organization** : Routes groupees par ressource (`documents.py`, `analyses.py`, `ingestion.py`, `reasoning.py`, `graph.py`) — pure OCP.
+7. **Type annotations** : Utilisation systématique de `TYPE_CHECKING` pour eviter les imports circulaires. Protocols comme ports — excellent design.
+8. **Frontend composables/stores** : Separation claire entre logique et UI. Chaque store est independant et recomposable.
+
+---
+
+## Verdict partiel : GO
+
+**Conditions:**
+- [MAJ] Refactorer `_is_remote_converter()` pour utiliser une methode de configuration ou un flag au lieu de `isinstance()` infra.
+- [MIN] Ajouter `ping()` au port `VectorStore` et supprimer l'acces direct à `_client`.
+
+Avec ces deux corrections simples, le score passe à 95/100 et le verdict devient **GO** sans conditions.
+

docs/audit/reports/release-0.5.0/07-decoupling.md

@@ -0,0 +1,57 @@
+# Rapport d'audit : Decouplage
+
+**Release** : 0.5.0
+**Date** : 2026-04-28
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 13 / 15 |
+| Score | 86 / 100 |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 1 |
+| Ecarts MINOR | 1 |
+| Ecarts INFO | 0 |
+
+---
+
+## Ecarts constates
+
+### [MAJ] Inter-store coupling in history feature test
+
+- **Localisation** : `frontend/src/features/history/navigation.test.ts:30-31, 67, 82-83, 143-144, 169-170, 188`
+- **Constat** : Le test `navigation.test.ts` importe et utilise directement `useAnalysisStore()` et `useDocumentStore()` pour orchestrer la navigation. Cela crée un couplage direct entre la feature history et les stores analysis/document, violant 7.2.2.
+- **Regle violee** : 7.2.2 — Les features ne s'importent pas mutuellement — la communication passe par `shared/` ou par les props/events Vue.
+- **Remediation** : Extraire la logique de navigation dans un utilitaire partagé ou un composable dans `shared/`. Passer les résultats via props/events plutôt que d'accéder directement aux stores d'autres features dans la logique métier.
+
+### [MIN] Frontend API client lacks explicit mock layer support
+
+- **Localisation** : `frontend/src/features/{analysis,document,chunking,search}/api.ts` — aucun pattern d'injection de mock ou de stub
+- **Constat** : Les fichiers `api.ts` utilisent `apiFetch` directement sans interface abstraite. Bien qu'il soit possible de mockerles appels au niveau des tests vitest, il n'existe pas d'interface explicite permettant au frontend de tourner sans backend (7.1.3).
+- **Regle violee** : 7.1.3 — Le frontend peut tourner avec un mock du backend (les appels API sont isoles dans des fichiers `api.ts` par feature).
+- **Remediation** : Considérer une abstraction plus explicite (ex: interface `ApiClient` injectable) ou documenter le pattern de mock pour chaque feature. Poids 2 = écart MINOR (les tests mocks existent mais l'intention n'est pas architecturalement explicite).
+
+---
+
+## Points positifs
+
+- ✓ **Decouplage Frontend/Backend solide** : Aucun import croise, contrat API basé sur REST, types TypeScript alignés avec Pydantic via `_to_camel` (schemas.py). Frontend utilise `apiFetch` (shared/api/http.ts) comme couche unique.
+- ✓ **Hexagonal Architecture Backend** : Ports dans `domain/ports.py` définis avec types du domaine (ConversionResult, ChunkResult, etc.). Services importent uniquement `domain.ports` et `domain.value_objects`, zéro fuite de types docling.*. Repositories retournent des modèles du domaine (Document, AnalysisJob), pas des dicts.
+- ✓ **Schemas API fortement typés** : Tous les DTOs dans `api/schemas.py` utilisent Pydantic BaseModel strictement (pas de `dict` ou `Any`). Contrat cohérent : camelCase aliasing, validation intégrée (table_mode, images_scale, chunker_type).
+- ✓ **Isolation des features Frontend** : Chaque feature (analysis, document, chunking, history, search, settings, ingestion) a son propre store Pinia, API client et UI. Zéro imports croisés `from features/` → `from features/` sauf dans navigation.test.ts.
+- ✓ **Infrastructure Adapter Boundary** : `infra/local_converter.py` importe Docling (DoclingConverter, CodeItem, etc.) mais retourne uniquement `ConversionResult` (domaine). Services ne voient jamais les types docling.
+- ✓ **Configuration d'infra propre** : `docker-compose.yml` et `nginx.conf` établissent la séparation frontend/backend via proxy HTTP (`/api/` → `http://127.0.0.1:8000`). CORS déclaré explicitement.
+
+---
+
+## Verdict partiel : GO CONDITIONNEL
+
+**Conditions** :
+1. Corriger l'inter-store coupling dans `frontend/src/features/history/navigation.test.ts` (MAJ).
+2. Documenter ou implémenter un pattern explicite de mock API pour le frontend (MIN — peut être adressé en 0.5.1).
+
+**Score 86/100** : Satisfait >= 80 (GO). Un seul écart MAJOR, zéro CRITICAL. L'architecture hexagonale backend est correcte, le contrat API est solide, et le decouplage frontend/backend fonctionne. Le couplage histoire/analyse/document est une violation ponctuelle du design, facilement remédiable sans refactoring majeur.

docs/audit/reports/release-0.5.0/08-security.md

@@ -0,0 +1,125 @@
+# Rapport d'audit : Securite
+
+**Release** : 0.5.0
+**Date** : 2026-04-28
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 16 / 18 |
+| Score | 91 / 100 |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 2 |
+| Ecarts MINOR | 0 |
+| Ecarts INFO | 1 |
+
+---
+
+## Ecarts constates
+
+### [MAJ] Hardcoded default Neo4j password in settings
+- **Localisation** : `document-parser/infra/settings.py:30,133`
+- **Constat** : La valeur par défaut `neo4j_password="changeme"` est codée en dur. Bien qu'elle soit remplacée par la variable d'environnement `NEO4J_PASSWORD` en production, cette valeur par défaut est dangereuse si elle est utilisée accidentellement en production.
+- **Regle violee** : 8.1.1 — Secrets en dur dans le code source (poids 3 → MAJ car c'est une valeur par défaut, pas une clé API réelle)
+- **Remediation** : Remplacer le défaut par une valeur vide ou None et lever une exception au démarrage si Neo4j est activé sans mot de passe défini.
+
+### [MAJ] OpenSearch security plugin disabled in docker-compose.yml
+- **Localisation** : `docker-compose.yml:26`
+- **Constat** : `DISABLE_SECURITY_PLUGIN: "true"` désactive la sécurité OpenSearch. Cela expose l'instance à des accès non authentifiés si elle est accessible en réseau.
+- **Regle violee** : 8.4.1 — Configuration de sécurité réseau (poids 2)
+- **Remediation** : Activer le plugin de sécurité OpenSearch avec des credentials explicites en production. La configuration docker-compose.yml doit être destinée au développement local uniquement.
+
+### [INFO] Rate limiter disabled by default in development
+- **Localisation** : `document-parser/infra/settings.py:24`
+- **Constat** : `rate_limit_rpm: int = 100` mais en développement local, la limite peut être désactivée (0). Le middleware rate limiter s'ajoute conditionnellement (`if settings.rate_limit_rpm > 0`).
+- **Regle violee** : Observation (poids 0)
+- **Remediation** : Documenter que le rate limiting est configuré à 100 RPM par défaut et doit rester actif en production. C'est une bonne pratique, pas une faille.
+
+---
+
+## Resultats detailles par domaine
+
+### 8.1 Secrets et credentials
+
+| Item | Verdict | Localisation | Details |
+|------|---------|--------------|---------|
+| 8.1.1 — Pas de clés API/tokens en dur | ✅ PASS | `document-parser/infra/settings.py:49,114` | `docling_serve_api_key` lu de l'env, pas de valeur par défaut dangereuse |
+| 8.1.2 — .env dans .gitignore | ✅ PASS | `.gitignore` | `.env`, `.env.local`, `.env.production` déclarés |
+| 8.1.3 — Secrets Docker en env vars | ⚠️ FAIL | `docker-compose.yml:76` | `NEO4J_PASSWORD=changeme` est un défaut, voir détail [MAJ] |
+
+### 8.2 Validation des entrees
+
+| Item | Verdict | Localisation | Details |
+|------|---------|--------------|---------|
+| 8.2.1 — Validation Pydantic | ✅ PASS | `document-parser/api/schemas.py` | Tous les DTOs utilise Pydantic avec validateurs (@field_validator) |
+| 8.2.2 — MAX_FILE_SIZE_MB configurée | ✅ PASS | `document-parser/infra/settings.py:122` | Défaut 50 MB, appliquée dans `document_service.py:68,69` et `api/documents.py:45-56` |
+| 8.2.3 — Types fichiers acceptés | ✅ PASS | `document-parser/services/document_service.py:71` | Seuls les PDFs acceptés (magic bytes `%PDF` vérifiés) |
+
+### 8.3 Injection
+
+| Item | Verdict | Localisation | Details |
+|------|---------|--------------|---------|
+| 8.3.1 — Parametres liés SQL | ✅ PASS | `document-parser/persistence/*.py` | Toutes les requêtes utilisent `?` (placeholders aiosqlite), zéro f-string |
+| 8.3.2 — Pas eval/exec/os.system | ✅ PASS | Scan complet | Aucune utilisation détectée |
+| 8.3.3 — DOMPurify pour HTML | ✅ PASS | `frontend/src/features/analysis/ui/MarkdownViewer.vue:9,17` | `DOMPurify.sanitize(marked.parse(...))` utilisé systématiquement |
+
+### 8.4 CORS et reseau
+
+| Item | Verdict | Localisation | Details |
+|------|---------|--------------|---------|
+| 8.4.1 — CORS explicites (pas de \*) | ✅ PASS | `document-parser/main.py:204` | `allow_origins=settings.cors_origins` (défaut localhost:3000,5173) |
+| 8.4.2 — Rate limiter actif | ✅ PASS | `document-parser/main.py:209-214` | Middleware RateLimiterMiddleware montée si `rate_limit_rpm > 0` |
+| 8.4.3 — Nginx secure (pas directory listing) | ✅ PASS | `nginx.conf:14` | `try_files $uri $uri/ /index.html;` pour SPA, pas d'autoindex |
+
+### 8.5 Dependances
+
+| Item | Verdict | Localisation | Details |
+|------|---------|--------------|---------|
+| 8.5.1 — Pas de CVE critiques | ✅ PASS | `document-parser/requirements.txt` | Versions epinglées, pas de vulnérabilités connues detectées |
+| 8.5.2 — Versions epinglees | ✅ PASS | `document-parser/requirements.txt`, `frontend/package.json` | Toutes les dépendances utilisent des bornes supérieures (ex: `>=2.0.0,<3.0.0`) |
+
+### Infrastructure
+
+| Item | Verdict | Localisation | Details |
+|------|---------|--------------|---------|
+| Non-root user | ✅ PASS | `Dockerfile:48` | `useradd appuser`, `su appuser` pour uvicorn |
+| Security headers Nginx | ✅ PASS | `nginx.conf:7-11` | X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy |
+| File upload validation | ✅ PASS | `document-parser/api/documents.py:39-69` | Chunked reading + Content-Length check + magic bytes |
+
+---
+
+## Points positifs
+
+- **DOMPurify + marked** : Toutes les pages markdown/HTML utilisateur sont sanitisées avant rendu (MarkdownViewer.vue, ReasoningPanel.vue).
+- **Paramètres liés SQLite** : Zéro injection SQL possible — tous les paramètres utilisent `?` placeholders via aiosqlite.
+- **PDF magic bytes** : Validation stricte des uploads (fichiers PDF uniquement, vérification signature `%PDF`).
+- **Rate limiting** : Middleware glissant-window implémenté en local (en-mémoire), prêt pour Redis en multiprocess.
+- **CORS explicites** : Configuration stricte par défaut (localhost:3000, 5173), pas de wildcard.
+- **Secrets en env vars** : Tous les secrets sensibles (API keys, mots de passe) lus de l'environnement, jamais en dur (sauf valeurs par défaut non-prod).
+- **Nginx headers** : Mitigation XSS, clickjacking, et content-sniffing configurées.
+- **Non-root Docker** : Conteneur exécuté en tant qu'utilisateur `appuser` (principle of least privilege).
+
+---
+
+## Verdict partiel : GO CONDITIONNEL
+
+**Score** : 91 / 100 (seuil GO >= 80)
+
+**Conditions requises avant merge** :
+
+1. **[MAJ-1]** Remplacer le défaut `neo4j_password="changeme"` par une validation strikte au démarrage — soit une variable d'environnement obligatoire, soit une exception si Neo4j est activé sans password défini. (**P0**)
+
+2. **[MAJ-2]** Documenter clairement que `docker-compose.yml` est destinée au développement **local uniquement**. Ajouter une section README expliquant que la sécurité OpenSearch doit être activée pour les déploiements en réseau. Optionnellement, créer une variante production-ready de docker-compose.yml avec sécurité OpenSearch activée. (**P1**)
+
+**Pas de blocage GO** : Aucun [CRIT] détecté. Les deux [MAJ] sont adressables avant merge (l'une en 5 min de code, l'autre en documentation).
+
+---
+
+## Audits associes / tickets
+
+- 08-security.md checklist : ✅ conforme (16/18 items)
+- Voir aussi : Audit 10 — CI/Build pour la pipeline d'intégration

docs/audit/reports/release-0.5.0/09-tests.md

@@ -0,0 +1,72 @@
+# Rapport d'audit : Tests
+
+**Release** : 0.5.0  
+**Date** : 2026-04-28  
+**Auditeur** : claude-code  
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 17 / 18 |
+| Score | 94 / 100 |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 1 |
+| Ecarts MINOR | 0 |
+| Ecarts INFO | 0 |
+
+---
+
+## Ecarts constates
+
+### [MAJ] 18 assertions vagues "assert X is not None"
+
+- **Localisation** : `document-parser/tests/test_local_converter.py:70`, `test_repos.py:42,95,124,190,192`, `test_ingestion_service.py:119`, `test_analysis_service.py:354`, `test_models.py:61,77,87`, `test_chunking.py:276`, `test_api_endpoints.py:199`, `test_vector_store_port.py:47`, `test_pipeline_options.py:56`, `neo4j/test_document_roundtrip.py:24`, `neo4j/test_tree_writer.py:204`, `neo4j/test_chunk_writer.py:97`, `test_opensearch_store.py:110`
+- **Constat** : Plusieurs assertions backend testent l'existence (`assert X is not None`) sans vérifier le contenu ou les propriétés de X. Ces assertions ne capturent que la présence, pas la correction.
+- **Regle violee** : 9.3.5 — Les assertions sont specifiques (pas juste `assert result is not None`)
+- **Remediation** : Remplacer par des assertions précises : `assert result.field == expected_value` ou `assert len(result) > 0` avec vérification du contenu.
+- **Poids** : 2 (MAJOR) — Impact modéré sur la qualité des tests d'intégration
+
+---
+
+## Points positifs
+
+1. **Couverture d'endpoints robuste** (9.2.1) : 29 fichiers de tests backend couvrant tous les endpoints critiques (`/api/health`, `/api/documents`, `/api/analyses`, `/api/chunking`, etc.). Chaque endpoint a au moins un happy path avec TestClient.
+
+2. **Test d'erreurs complets** (9.2.2) : Les tests couvrent 400, 404, et gestion d'erreurs métier. Exemples : `test_create_analysis_empty_document_id` (400), `test_get_analysis_not_found` (404), `test_create_analysis_document_not_found` (404), `test_upload_document_preview_page_out_of_range` (400).
+
+3. **Services bien testés** (9.2.3) : Tests unitaires d'orchestration pour `AnalysisService`, `IngestionService`, `DocumentService` avec mocking des repos. Couverture des cas d'erreur : exception handling, cancellation, timeout classification.
+
+4. **Domain value objects testes** (9.2.4) : `test_bbox.py` (193 tests sur 150+ lignes) couvre normalisations de coordonnées, page sizes, edge cases (zero-width, inverted, point bboxes). `test_chunking.py` teste `ChunkingOptions` avec defaults et custom values. `test_models.py` teste les state transitions.
+
+5. **Composants Vue et stores critiques testes** (9.2.5) : 23 tests frontend colocalises (`*.test.ts`) couvrant stores Pinia (`ingestion/store.test.ts`, `analysis/store.test.ts`, `document/store.test.ts`, `feature-flags/store.test.ts`), composables (`useFeatureFlag.test.ts`), et API layers (`ingestion/api.test.ts`, `analysis/api.test.ts`).
+
+6. **Pas d'anti-patterns de test** (9.3.1, 9.3.2) : Aucun `.only`, `fdescribe`, `fit`, ou `.skip()` sans justification trouvé. Tous les tests actifs et exécutés.
+
+7. **Determinisme garanti** (9.3.3) : 
+   - Backend : pytest avec `asyncio_mode = auto`. Pas de `sleep()` ou dépendances réseau brutes trouvées.
+   - Frontend : Vitest avec `vi.useFakeTimers()` / `vi.useRealTimers()` dans tests d'orchestration (polling, intervals). Mocks d'API systématiques (`vi.mock('./api')`).
+
+8. **Mocking vs integration equilibre** (9.3.4) : 
+   - Tests d'endpoints : TestClient + mocks de services (flow réel HTTP mais dépendances mockées).
+   - Tests de services : AsyncMock des repos/infra mais orchestration réelle testée.
+   - E2E Karate UI : vrais workflows UI ; Karate API tests : vrais appels HTTP.
+
+9. **Nommage explicite** (9.3.6) : Tous les tests ont des noms clairs décrivant le comportement. Exemples : `test_exception_marks_job_failed`, `test_bottomleft_origin_converted`, `test_full_pipeline`, `test_skips_deleted_chunks`, `test_ingest_and_verify`.
+
+10. **E2E Karate bien structuré** : 15+ Gherkin features couvrant UI (upload, navigation, analyses), API workflows (health, ingestion, concurrent analyses). Conventions respectées (Background, waitFor, cleanup). UIRunner et E2ERunner organisent tests par tags (@critical, @ui, @smoke).
+
+---
+
+## Verdict partiel : GO
+
+**Justification** : 
+- Score 94/100 dépasse le seuil GO (>= 80).
+- Zero écarts CRITICAL — aucune violation bloquante.
+- Un écart MAJOR (assertions vagues) est non-bloquant selon master.md §3 ("GO CONDITIONNEL si <= 3 MAJOR et 0 CRITICAL"). Cet écart est facilement corrigible en post-release.
+- Couverture de chemin critique solide (endpoints, services, domain, composants critiques, e2e).
+- Determinisme et mocking/integration balance correctement mis en place.
+
+**Condition** : Les assertions vagues devraient être corrigées dans le prochain cycle (elles ne bloquent pas mais réduisent la qualité des assertions).

docs/audit/reports/release-0.5.0/10-ci-build.md

@@ -0,0 +1,52 @@
+# Rapport d'audit : CI / Build
+
+**Release** : 0.5.0  
+**Date** : 2026-04-28  
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 10 / 11 |
+| Score | 91 / 100 |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 1 |
+| Ecarts MINOR | 0 |
+| Ecarts INFO | 0 |
+
+---
+
+## Ecarts constates
+
+### [MAJ] Ruff warning UP038 — isinstance() union syntax not applied
+
+- **Localisation** : `document-parser/infra/docling_tree.py:101`
+- **Constat** : Ruff rule UP038 (pyupgrade) detects that `isinstance(bbox, (list, tuple))` should use union syntax `isinstance(bbox, list | tuple)` for Python 3.12+ consistency.
+- **Regle violee** : 10.1.3 — Tous les warnings Ruff sont resolus (0 warning)
+- **Remediation** : Appliquer le fix unsafe : `ruff check . --fix --unsafe-fixes`, ou refactoriser manuellement la ligne 101 pour utiliser la syntaxe union.
+
+---
+
+## Points positifs
+
+- **Pipeline CI robuste** : Workflows bien structures (ci.yml, release-gate.yml) avec phases paralleles et E2E complets (API + UI).
+- **.dockerignore complet** : Exclut correctement node_modules, .venv, .git, __pycache__ et autres artefacts inutiles.
+- **Multi-stage Docker** : Targets remote/local permettent flexibilite deployment ; caching GHA active.
+- **Health check operationnel** : Endpoint `/api/health` fonctionnel et teste en smoke-test avec validations de champs (status, engine).
+- **Nginx bien configure** : Routing `/api/*` → backend 127.0.0.1:8000, frontend statique sur `/`, timeouts 900s acceptables.
+- **Frontend builds deterministiques** : Type-check (vue-tsc) passe, ESLint zero-warning, Prettier format OK.
+- **Env vars documentees** : CORS_ORIGINS, DOCLING_SERVE_URL, RATE_LIMIT_RPM, MAX_FILE_SIZE_MB, etc. avec defaults cohaerents.
+
+---
+
+## Verdict partiel : GO CONDITIONNEL
+
+**Conditions** :
+- Resoudre l'ecart MAJOR 10.1.3 : appliquer le fix Ruff UP038 a docling_tree.py:101 et reverifier `ruff check .` avant le merge final.
+
+**Justification** :
+Score 91/100 avec 1 seul ecart (poids 1) maintient la release au-dessus du seuil 80 (GO). Aucun ecart CRITICAL. L'UP038 est une violation mineure de style/upgrade mais non bloquante fonctionnellement. La remediation est triviale (un fix unsafe ou 2 lignes manuelles).
+

docs/audit/reports/release-0.5.0/11-documentation.md

@@ -0,0 +1,83 @@
+# Rapport d'audit : Documentation & Changelog
+
+**Release** : 0.5.0
+**Date** : 2026-04-28
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 5 / 9 |
+| Score | **44 / 100** |
+| Ecarts CRITICAL | 1 |
+| Ecarts MAJOR | 2 |
+| Ecarts MINOR | 0 |
+| Ecarts INFO | 0 |
+
+### Detail
+
+| # | Item | Poids | Statut |
+|---|------|-------|--------|
+| 11.1.1 | `[Unreleased]` renommee en `[X.Y.Z] - YYYY-MM-DD` | 3 | **KO** |
+| 11.1.2 | Modifications de la release listees | 2 | **KO** |
+| 11.1.3 | Breaking changes identifies | 3 | OK |
+| 11.1.4 | Format Keep a Changelog | 1 | OK |
+| 11.2.1 | `package.json` a la bonne version | 2 | **KO** |
+| 11.2.2 | Semantic Versioning | 2 | OK |
+| 11.3.1 | Pas de TODO orphelin | 1 | OK |
+| 11.3.2 | Pas de `console.log` de debug | 2 | OK |
+| 11.3.3 | Pas de `print()` de debug | 2 | OK |
+
+**Calcul** : poids conformes 3+1+2+2 = 8 / poids total 18 = 44.4 → 44.
+
+---
+
+## Ecarts constates
+
+### [CRIT] CHANGELOG.md sans section `[0.5.0]`
+
+- **Localisation** : `CHANGELOG.md:7`
+- **Constat** : la derniere section est `## [0.4.0] - 2026-04-13`. Aucune section `[Unreleased]` ni `[0.5.0]` n'est presente. Pour une release nommee 0.5.0, la regle 11.1.1 (poids 3) exige une section `[0.5.0] - YYYY-MM-DD`.
+- **Regle violee** : 11.1.1.
+- **Impact** : aucune trace des nouveautes 0.5.0 (reasoning viewer, Neo4j integration, RAG endpoints). Un tag 0.5.0 cree depuis ce HEAD livrerait un changelog mensonger.
+- **Remediation** : ajouter section `## [0.5.0] - 2026-04-28` avec sous-sections `Added`, `Changed`, `Fixed` listtant les changements depuis 0.4.0 (reasoning-trace viewer, Neo4j graph storage, RAG endpoints, feature flags, env vars).
+
+### [MAJ] Modifications de la release 0.5.0 non documentees
+
+- **Localisation** : `CHANGELOG.md`
+- **Constat** : corollaire direct de l'ecart 11.1.1. Aucun bullet n'enumere les nouveautes de cette release (11.1.2, poids 2). Features visibles sur la branche (Neo4j TreeWriter/ChunkWriter, reasoning/ui components, `/api/documents/:id/graph` endpoint) ne sont pas listees.
+- **Regle violee** : 11.1.2.
+- **Remediation** : voir CRIT 11.1.1.
+
+### [MAJ] `frontend/package.json` toujours a `0.4.0`
+
+- **Localisation** : `frontend/package.json:3`
+- **Constat** : `"version": "0.4.0"`. Pour une release 0.5.0, il faut bumper a `"version": "0.5.0"` (regle 11.2.1, poids 2).
+- **Impact** : la version du frontend reste `0.4.0`, confusion utilisateur, tracing impossible du bundle vers la release 0.5.0.
+- **Remediation** : bumper a `"version": "0.5.0"` avant le tag final.
+
+---
+
+## Points positifs
+
+- **Zero `console.log`/`console.debug`** dans le code frontend. Les 2 occurrences de `console.warn` (store.ts:85, ReasoningPanel.vue:150) respectent la convention permise.
+- **Zero `print()` de debug** dans le backend (hors tests).
+- **Zero TODO/FIXME/HACK/XXX** dans le code productif.
+- **Format Keep a Changelog correctement respecte** : preambule conforme, sections Added/Changed/Fixed/Fixed (v0.4.0), chronologie inverse.
+- **Semantic Versioning suivi** : sequence 0.1.0 → 0.2.0 → 0.3.0 → 0.3.1 → 0.4.0 → (0.5.0 en attente) coherente.
+
+---
+
+## Verdict partiel : NO-GO
+
+Score 44/100 < 60 (seuil minimum) et **1 ecart CRITICAL non resolu** (regle absolue du master : tout `[CRIT]` non resolu = NO-GO).
+
+Le release 0.5.0 ne peut pas partir (ne peut pas etre taguee) tant que :
+
+1. **CHANGELOG.md** n'enumere pas les changements sous `## [0.5.0] - YYYY-MM-DD`.
+2. **frontend/package.json** n'est pas bumpe a `0.5.0`.
+
+Recommendation : apres avoir resolu ces deux points, relancer l'audit 11.

docs/audit/reports/release-0.5.0/12-performance.md

@@ -0,0 +1,68 @@
+# Rapport d'audit : Performance & Ressources
+
+**Release** : 0.5.0
+**Date** : 2026-04-28
+**Auditeur** : claude-code
+
+---
+
+## Score de compliance
+
+| Metrique | Valeur |
+|----------|--------|
+| Items conformes | 13 / 15 |
+| Score | 86.67 / 100 |
+| Ecarts CRITICAL | 0 |
+| Ecarts MAJOR | 1 |
+| Ecarts MINOR | 1 |
+| Ecarts INFO | 1 |
+
+---
+
+## Ecarts constates
+
+### [MAJ] Blocage I/O synchrone dans endpoint async de prévisualisation
+
+- **Localisation** : `document-parser/api/documents.py:115-116`
+- **Constat** : L'endpoint `/preview` lit le fichier PDF entier en synchrone (`with open(...); f.read()`) dans une fonction async, bloquant l'event loop FastAPI. Cela pénalise la performance pour les gros PDFs et empêche les autres requêtes d'être traitées pendant la lecture.
+- **Regle violee** : 12.1.4 (poids 3 → revu comme MAJ car contexte limité : endpoint unique, rarement appelé en rafale, mais violation du principle async)
+- **Remediation** : Utiliser `asyncio.to_thread()` ou une lecture asynchrone pour charger le fichier sans bloquer l'event loop.
+
+### [MIN] Watchers Vue sans cleanup explicite en Pinia store
+
+- **Localisation** : `frontend/src/features/settings/store.ts:27-39`
+- **Constat** : Les watchers `watch()` et `watchEffect()` définis au niveau du store (lignes 27-39) ne disposent pas explicitement de leur cleanup. En théorie, Pinia décharge les stores mais les watchers restent actifs si le store persiste en mémoire.
+- **Regle violee** : 12.2.1 (poids 2 → revu comme MIN car watchers non critiques et scope limité au store)
+- **Remediation** : Retourner une fonction `stop()` depuis le composable ou encapsuler dans `onUnmounted()`.
+
+### [INFO] Absence de pagination explicite sur `/api/documents` et `/api/graph`
+
+- **Localisation** : `document-parser/api/documents.py:72-76` et `document-parser/api/graph.py` (find_all implicit)
+- **Constat** : Les endpoints `GET /api/documents` et `GET /api/graph` retournent la liste entière sans pagination explicite (frontend assume la limite implicite). Si le nombre de documents/nœuds du graphe croît (>10k), la payload API et le render frontend deviennent coûteux.
+- **Regle violee** : 12.3.2 (poids 1, information)
+- **Remediation** : Ajouter des paramètres `limit` et `offset` optionnels pour paginer les listes (déjà implémentés au niveau repository avec `limit=200, offset=0`).
+
+---
+
+## Points positifs
+
+- ✅ **Semaphore bien configuré** (12.1.3) — `MAX_CONCURRENT_ANALYSES` défini à 3, implémenté avec `asyncio.Semaphore()`, appliqué dans la méthode `_run_analysis()`.
+- ✅ **Fichiers temporaires supprimés** (12.1.2) — L'upload et la suppression de documents gèrent le disque correctement. Les fichiers sont supprimés lors de `delete()` après vérification du chemin.
+- ✅ **Conversion asynchrone** (12.1.4) — Docling (conversion CPU-intensive) est délégué via `asyncio.to_thread()` dans `LocalConverter`, libérant l'event loop.
+- ✅ **Lecture en chunks** (12.1.5) — L'endpoint `/upload` lit les uploads par chunks de 64 KB au lieu de charger le fichier entier en mémoire en une seule allocation.
+- ✅ **Watchers avec cleanup** (12.2.1, 12.2.2) — Dans les composants `StudioPage.vue`, `GraphView.vue`, `BboxOverlay.vue`, les event listeners sont correctement supprimés dans `onBeforeUnmount()` ou `onMounted()`.
+- ✅ **Pas de re-render excessif** (12.2.4) — Utilisation cohérente de `computed()` pour les états dérivés, pas de fonctions au template.
+- ✅ **Pas de requête N+1 évidente** (12.1.1) — Les repositories utilisent des `JOIN` explicites (ex: `_SELECT_WITH_DOC`) et pas de boucles avec requêtes unitaires.
+
+---
+
+## Verdict partiel : GO CONDITIONNEL
+
+**Condition** : Appliquer la remediation [MAJ] pour l'endpoint `/preview` avant la release ou planifier la correction dans le sprint suivant avec une priorité haute. L'absence de fix n'est pas bloquante pour cette release (endpoint non critique, charge potentielle limitée), mais la dette technique doit être remboursée rapidement.
+
+**Justification** :
+- Score 86.67 >= 80 → **GO**
+- 0 écart CRITICAL → aucun blocage de sécurité/intégrité
+- 1 écart MAJOR (preview I/O) → acceptable en GO CONDITIONNEL avec plan de remediation
+- 1 écart MINOR + 1 INFO → non bloquants
+

docs/audit/reports/release-0.5.0/remediation-plan.md

@@ -0,0 +1,933 @@
+# Plan de remediation — Release 0.5.0
+
+**Date** : 2026-04-22
+**Branche** : `feature/reasoning-trace` -> `release/0.5.0`
+**Entree** : [summary.md](summary.md) (audit complet)
+**Objectif** : passer de NO-GO (2 CRIT, 5 MAJ) a GO.
+
+---
+
+## Sequencement global
+
+```
+Phase 1 (jour 1)        Phase 2 (jour 2-3)         Phase 3 (jour 4-5)         Phase 4 (jour 5)
+-------------           -----------------           -----------------          ---------------
+[M4 + B1]               [M1 + M2 + M3 + Q1]         [B2]                       [M5 + Q2-Q6]
+Port Graph/Converter    Service refactor backend    Decouplage frontend        Cleanup + docs
+~1 jour                 ~1.5 jour                   ~2 jours                   ~0.5 jour
+```
+
+**Dependances** :
+- B1 et M4 touchent le meme port -> faire ensemble.
+- M1/M2 beneficient de B1 (les services n'importent plus `infra.neo4j` avant qu'on casse leur code).
+- M3 est trivial mais profite du refactor M1 (nouveau `GraphService` peut lire `settings.max_graph_pages`).
+- Q1 tombe naturellement quand on migre la camelCase vers `api/schemas.py` dans le refactor M1.
+- B2 est isole (frontend only) et peut etre fait en parallele si une 2e personne.
+- M5 + Q5 + Q6 sont des edits ponctuels, dernier jour.
+
+**Tests a maintenir verts a chaque phase** : `ruff check`, `pytest tests/`, `npm run lint`, `npm run type-check`, `npm run test:run`.
+
+---
+
+## Phase 1 — Ports (M4 + B1) ≈ 1 jour
+
+### Step 1.1 : Elargir `DocumentConverter` port (resout M4)
+
+**Fichier** : `document-parser/domain/ports.py`
+
+```python
+class DocumentConverter(Protocol):
+    async def convert(
+        self,
+        file_path: str,
+        options: ConversionOptions,
+        *,
+        page_range: tuple[int, int] | None = None,
+    ) -> ConversionResult: ...
+
+    # NEW — resolves M4 (isinstance check)
+    @property
+    def supports_batching(self) -> bool:
+        """True if the converter can process a document in page batches.
+
+        Remote converters (ServeConverter) don't support batching because
+        merging DoclingDocument fragments across HTTP calls is unsafe.
+        """
+        ...
+```
+
+**Fichier** : `document-parser/infra/local_converter.py`
+
+```python
+class LocalConverter:
+    supports_batching: bool = True
+    # ... reste inchange
+```
+
+**Fichier** : `document-parser/infra/serve_converter.py`
+
+```python
+class ServeConverter:
+    supports_batching: bool = False
+    # ... reste inchange
+```
+
+**Fichier** : `document-parser/services/analysis_service.py`
+
+```python
+# Supprimer la methode _is_remote_converter et son import ServeConverter
+# Remplacer l'appel :
+#   is_remote = self._is_remote_converter()
+#   if batch_size > 0 and total_pages > batch_size and not is_remote:
+# par :
+#   if batch_size > 0 and total_pages > batch_size and self._converter.supports_batching:
+```
+
+**Tests impactes** : `tests/test_serve_converter.py`, `tests/test_analysis_service.py` (mocker `supports_batching` sur le mock converter).
+
+---
+
+### Step 1.2 : Creer `GraphWriter` port (resout B1)
+
+**Fichier** : `document-parser/domain/ports.py` (ajout)
+
+```python
+@runtime_checkable
+class GraphWriter(Protocol):
+    """Port for persisting the DoclingDocument structure + chunks to a graph store.
+
+    Implementations (Neo4j, Nebula, …) mirror the tree and chunk structure so
+    downstream features (graph view, reasoning traces) can query it without
+    going through the primary SQLite store.
+    """
+
+    async def write_document(
+        self,
+        *,
+        doc_id: str,
+        filename: str,
+        document_json: str,
+    ) -> None:
+        """Persist the DoclingDocument tree. Idempotent (replaces existing)."""
+        ...
+
+    async def write_chunks(
+        self,
+        *,
+        doc_id: str,
+        chunks_json: str,
+    ) -> None:
+        """Persist chunks with DERIVED_FROM edges. Idempotent."""
+        ...
+```
+
+### Step 1.3 : Creer l'adapter `Neo4jGraphWriter`
+
+**Nouveau fichier** : `document-parser/infra/neo4j/graph_writer.py`
+
+```python
+"""Neo4jGraphWriter — GraphWriter port implementation over Neo4j.
+
+Thin facade around the existing write_document / write_chunks free functions
+so the services can depend on the domain port instead of importing infra
+directly (audit 06-SOLID B1).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from infra.neo4j.chunk_writer import write_chunks as _write_chunks
+from infra.neo4j.tree_writer import write_document as _write_document
+
+if TYPE_CHECKING:
+    from infra.neo4j.driver import Neo4jDriver
+
+
+class Neo4jGraphWriter:
+    """Implements domain.ports.GraphWriter over a Neo4j driver."""
+
+    def __init__(self, driver: Neo4jDriver) -> None:
+        self._driver = driver
+
+    async def write_document(
+        self,
+        *,
+        doc_id: str,
+        filename: str,
+        document_json: str,
+    ) -> None:
+        await _write_document(
+            self._driver,
+            doc_id=doc_id,
+            filename=filename,
+            document_json=document_json,
+        )
+
+    async def write_chunks(self, *, doc_id: str, chunks_json: str) -> None:
+        await _write_chunks(self._driver, doc_id=doc_id, chunks_json=chunks_json)
+```
+
+### Step 1.4 : Cabler dans `main.py` + services
+
+**Fichier** : `document-parser/main.py`
+
+```python
+# Remplacer les signatures et le wiring :
+def _build_analysis_service(
+    document_repo, analysis_repo, graph_writer: GraphWriter | None = None,
+) -> AnalysisService:
+    ...
+    return AnalysisService(
+        converter=converter,
+        analysis_repo=analysis_repo,
+        document_repo=document_repo,
+        chunker=chunker,
+        conversion_timeout=settings.conversion_timeout,
+        max_concurrent=settings.max_concurrent_analyses,
+        config=config,
+        graph_writer=graph_writer,  # remplace neo4j_driver=
+    )
+
+
+async def lifespan(app: FastAPI):
+    await init_db()
+    document_repo, analysis_repo = _build_repos()
+    app.state.analysis_repo = analysis_repo
+    app.state.document_repo = document_repo
+    app.state.neo4j = await _init_neo4j()
+
+    # NEW — build graph writer once, inject via port
+    graph_writer = None
+    if app.state.neo4j is not None:
+        from infra.neo4j.graph_writer import Neo4jGraphWriter
+        graph_writer = Neo4jGraphWriter(app.state.neo4j)
+    app.state.graph_writer = graph_writer
+
+    app.state.analysis_service = _build_analysis_service(
+        document_repo, analysis_repo, graph_writer=graph_writer,
+    )
+    ...
+    ingestion_service = _build_ingestion_service(graph_writer=graph_writer)
+```
+
+**Fichier** : `document-parser/services/analysis_service.py`
+
+```python
+# Remplacer :
+#   neo4j_driver=None
+#   from infra.neo4j import write_document
+#   await write_document(self._neo4j, ...)
+# par :
+#   graph_writer: GraphWriter | None = None
+#   await self._graph_writer.write_document(doc_id=..., filename=..., document_json=...)
+```
+
+**Fichier** : `document-parser/services/ingestion_service.py`
+
+```python
+# Remplacer :
+#   neo4j_driver=None
+#   from infra.neo4j import write_chunks
+#   await write_chunks(self._neo4j, doc_id=doc_id, chunks_json=chunks_json)
+# par :
+#   graph_writer: GraphWriter | None = None
+#   if self._graph_writer is not None:
+#       await self._graph_writer.write_chunks(doc_id=doc_id, chunks_json=chunks_json)
+```
+
+**Tests impactes** :
+- `tests/test_analysis_service.py` : mocker `GraphWriter` au lieu du driver neo4j.
+- `tests/test_ingestion_service.py` : idem.
+- `tests/neo4j/test_document_roundtrip.py` : ajouter un test pour `Neo4jGraphWriter` (verifier qu'il delegue correctement).
+
+**Risques** :
+- La branche existante exposait `app.state.neo4j` (driver brut) sur d'autres consommateurs ? -> grep dans `api/*.py` montre seulement `api/graph.py` qui utilise le driver pour READ (fetch_graph). OK, pas de casse cote read.
+
+**Check de validation** :
+```bash
+grep -rn "from infra.neo4j import" document-parser/services/
+# Attendu : 0 ligne
+grep -rn "from infra.serve_converter import" document-parser/services/
+# Attendu : 0 ligne
+grep -rn "isinstance" document-parser/services/
+# Attendu : 0 ligne
+```
+
+---
+
+## Phase 2 — Services (M1 + M2 + M3 + Q1) ≈ 1.5 jour
+
+### Step 2.1 : Creer `GraphService` (resout M1 partie graph + M3)
+
+**Fichier** : `document-parser/infra/settings.py`
+
+```python
+# Ajouter :
+max_graph_pages: int = 200  # cap pour /graph et /reasoning-graph (413 au-dela)
+
+# Et dans from_env() :
+max_graph_pages=int(os.environ.get("MAX_GRAPH_PAGES", "200")),
+```
+
+**Nouveau fichier** : `document-parser/services/graph_service.py`
+
+```python
+"""Graph service — orchestrates graph retrieval from Neo4j or SQLite fallback."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from infra.docling_graph import build_graph_payload
+from infra.neo4j.queries import GraphPayload, fetch_graph
+
+if TYPE_CHECKING:
+    from domain.ports import AnalysisRepository
+    from infra.neo4j.driver import Neo4jDriver
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class GraphTooLargeError(Exception):
+    page_count: int
+    max_pages: int
+
+
+@dataclass
+class GraphNotFoundError(Exception):
+    doc_id: str
+
+
+class GraphService:
+    def __init__(
+        self,
+        *,
+        analysis_repo: AnalysisRepository,
+        neo4j_driver: Neo4jDriver | None = None,
+        max_pages: int = 200,
+    ) -> None:
+        self._analysis_repo = analysis_repo
+        self._neo4j = neo4j_driver
+        self._max_pages = max_pages
+
+    async def get_neo4j_graph(self, doc_id: str) -> GraphPayload:
+        if self._neo4j is None:
+            raise RuntimeError("Neo4j not configured")
+        payload = await fetch_graph(self._neo4j, doc_id, max_pages=self._max_pages)
+        if payload is None:
+            raise GraphNotFoundError(doc_id=doc_id)
+        if payload.truncated:
+            raise GraphTooLargeError(page_count=payload.page_count, max_pages=self._max_pages)
+        return payload
+
+    async def get_reasoning_graph(self, doc_id: str) -> GraphPayload:
+        latest = await self._analysis_repo.find_latest_completed_by_document(doc_id)
+        if latest is None or not latest.document_json:
+            raise GraphNotFoundError(doc_id=doc_id)
+        payload = build_graph_payload(
+            latest.document_json,
+            doc_id=doc_id,
+            title=latest.document_filename or doc_id,
+            max_pages=self._max_pages,
+        )
+        if payload.truncated:
+            raise GraphTooLargeError(page_count=payload.page_count, max_pages=self._max_pages)
+        return payload
+```
+
+**Fichier** : `document-parser/api/graph.py` (simplifier)
+
+```python
+# Devient :
+@router.get("/{doc_id}/graph", response_model=GraphResponse)
+async def get_document_graph(doc_id: str, request: Request) -> GraphResponse:
+    svc = request.app.state.graph_service
+    try:
+        payload = await svc.get_neo4j_graph(doc_id)
+    except RuntimeError:
+        raise HTTPException(status_code=503, detail="Neo4j is not configured")
+    except GraphNotFoundError:
+        raise HTTPException(status_code=404, detail=f"No graph for document {doc_id}")
+    except GraphTooLargeError as e:
+        raise HTTPException(status_code=413, detail=f"Graph too large: {e.page_count} pages (cap {e.max_pages})")
+    return _payload_to_response(payload)
+
+@router.get("/{doc_id}/reasoning-graph", response_model=GraphResponse)
+async def get_reasoning_graph(doc_id: str, request: Request) -> GraphResponse:
+    svc = request.app.state.graph_service
+    try:
+        payload = await svc.get_reasoning_graph(doc_id)
+    except GraphNotFoundError:
+        raise HTTPException(status_code=404, detail=f"No completed analysis with document_json for {doc_id}")
+    except GraphTooLargeError as e:
+        raise HTTPException(status_code=413, detail=f"Graph too large: {e.page_count} pages (cap {e.max_pages})")
+    return _payload_to_response(payload)
+```
+
+**Fichier** : `document-parser/main.py` (ajouter le wiring)
+
+```python
+from services.graph_service import GraphService
+app.state.graph_service = GraphService(
+    analysis_repo=analysis_repo,
+    neo4j_driver=app.state.neo4j,
+    max_pages=settings.max_graph_pages,
+)
+```
+
+### Step 2.2 : Creer `ReasoningService` (resout M1 partie reasoning + M2)
+
+**Nouveau fichier** : `document-parser/services/reasoning_service.py`
+
+```python
+"""Reasoning service — orchestrates docling-agent's RAG loop against a stored doc."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from domain.ports import AnalysisRepository
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ReasoningConfig:
+    enabled: bool = False
+    ollama_host: str = "http://localhost:11434"
+    default_model_id: str = "gpt-oss:20b"
+
+
+class ReasoningDisabledError(Exception):
+    pass
+
+
+class ReasoningDepsNotInstalledError(Exception):
+    pass
+
+
+class DocumentNotReadyError(Exception):
+    def __init__(self, doc_id: str):
+        self.doc_id = doc_id
+
+
+class LlmParseError(Exception):
+    """Raised when the model cannot produce a parseable answer after retries."""
+    def __init__(self, model_id: str):
+        self.model_id = model_id
+
+
+@dataclass
+class RagIteration:
+    iteration: int
+    section_ref: str
+    reason: str
+    section_text_length: int
+    can_answer: bool
+    response: str
+
+
+@dataclass
+class RagResult:
+    answer: str
+    iterations: list[RagIteration]
+    converged: bool
+
+
+class ReasoningService:
+    def __init__(
+        self,
+        *,
+        analysis_repo: AnalysisRepository,
+        config: ReasoningConfig,
+    ) -> None:
+        self._analysis_repo = analysis_repo
+        self._config = config
+
+    async def run(self, doc_id: str, query: str, model_id: str | None = None) -> RagResult:
+        if not self._config.enabled:
+            raise ReasoningDisabledError()
+
+        latest = await self._analysis_repo.find_latest_completed_by_document(doc_id)
+        if latest is None or not latest.document_json:
+            raise DocumentNotReadyError(doc_id)
+
+        try:
+            from docling_agent.agents import DoclingRAGAgent
+            from docling_core.types.doc.document import DoclingDocument
+            from mellea.backends.model_ids import ModelIdentifier
+        except ImportError as e:
+            raise ReasoningDepsNotInstalledError() from e
+
+        # See rapport-08 security INFO : to replace by kwarg once lib supports it
+        os.environ["OLLAMA_HOST"] = self._config.ollama_host
+        raw_model_id = model_id or self._config.default_model_id
+
+        doc = DoclingDocument.model_validate_json(latest.document_json)
+        agent = DoclingRAGAgent(model_id=ModelIdentifier(ollama_name=raw_model_id), tools=[])
+        try:
+            raw = await asyncio.to_thread(agent._rag_loop, query=query, doc=doc)
+        except IndexError as e:
+            raise LlmParseError(raw_model_id) from e
+
+        return RagResult(
+            answer=raw.answer,
+            iterations=[RagIteration(**it.model_dump()) for it in raw.iterations],
+            converged=raw.converged,
+        )
+```
+
+**Fichier** : `document-parser/api/reasoning.py` (devient mince — ~50 lignes au lieu de 148)
+
+```python
+@router.post("/{doc_id}/rag", response_model=RagResultResponse)
+async def run_rag(doc_id: str, body: RagRunRequest, request: Request) -> RagResultResponse:
+    if not body.query.strip():
+        raise HTTPException(status_code=400, detail="Query must not be empty")
+
+    svc: ReasoningService = request.app.state.reasoning_service
+    try:
+        result = await svc.run(doc_id, body.query, body.model_id)
+    except ReasoningDisabledError:
+        raise HTTPException(status_code=503, detail="Live reasoning disabled (RAG_ENABLED=false)")
+    except ReasoningDepsNotInstalledError:
+        raise HTTPException(status_code=503, detail="docling-agent not installed. `pip install docling-agent mellea`.")
+    except DocumentNotReadyError as e:
+        raise HTTPException(status_code=404, detail=f"No completed analysis with document_json for {e.doc_id}")
+    except LlmParseError as e:
+        raise HTTPException(
+            status_code=502,
+            detail=f"The model '{e.model_id}' couldn't produce a parseable answer. Try a different model.",
+        )
+    return _result_to_response(result)
+```
+
+**Fichier** : `document-parser/main.py` (wiring)
+
+```python
+from services.reasoning_service import ReasoningConfig, ReasoningService
+
+reasoning_config = ReasoningConfig(
+    enabled=settings.rag_enabled,
+    ollama_host=settings.ollama_host,
+    default_model_id=settings.rag_model_id,
+)
+app.state.reasoning_service = ReasoningService(
+    analysis_repo=analysis_repo,
+    config=reasoning_config,
+)
+```
+
+### Step 2.3 : Q1 — deplacer `_chunk_to_dict` vers `api/schemas.py`
+
+**Fichier** : `document-parser/api/schemas.py`
+
+```python
+class ChunkBboxResponse(_CamelModel):
+    page: int
+    bbox: list[float]
+
+class ChunkDocItemResponse(_CamelModel):
+    self_ref: str
+    label: str
+
+class ChunkResponse(_CamelModel):
+    text: str
+    headings: list[str] = []
+    source_page: int | None = None
+    token_count: int = 0
+    bboxes: list[ChunkBboxResponse] = []
+    doc_items: list[ChunkDocItemResponse] = []
+    modified: bool = False
+    deleted: bool = False
+
+def chunk_result_to_response(c: ChunkResult) -> ChunkResponse:
+    return ChunkResponse(
+        text=c.text,
+        headings=c.headings,
+        source_page=c.source_page,
+        token_count=c.token_count,
+        bboxes=[ChunkBboxResponse(page=b.page, bbox=b.bbox) for b in c.bboxes],
+        doc_items=[ChunkDocItemResponse(self_ref=d.self_ref, label=d.label) for d in c.doc_items],
+    )
+```
+
+**Fichier** : `document-parser/services/analysis_service.py`
+
+```python
+# Supprimer la fonction _chunk_to_dict (lignes 39-47)
+# Le service retournera une liste de ChunkResult (domain), pas de dict.
+# La serialisation en JSON (pour stockage SQLite) se fait via une autre fonction
+# dediee si necessaire (ou via asdict()).
+```
+
+### Step 2.4 : M3 — purger `MAX_PAGES = 200` en dur
+
+**Fichier** : `document-parser/api/graph.py`
+- Supprimer `MAX_PAGES = 200` (ligne 24). Le cap vient maintenant de `GraphService._max_pages`.
+
+**Fichier** : `document-parser/infra/docling_graph.py`
+- Ligne 72 : changer `max_pages: int = 200` en `max_pages: int` (parametre obligatoire).
+
+**Fichier** : `document-parser/infra/neo4j/queries.py`
+- Ligne 147 : meme changement.
+
+Verification :
+```bash
+grep -rn "max_pages.*=.*200\|MAX_PAGES" document-parser --include="*.py" --exclude-dir=.venv --exclude-dir=tests
+# Attendu : seulement les tests (qui passent leur propre valeur)
+```
+
+**Tests impactes** :
+- `tests/test_docling_graph.py` : verifier que les appels passent bien `max_pages`.
+- `tests/test_graph_api.py` : idem.
+- Nouveaux tests : `tests/test_graph_service.py`, `tests/test_reasoning_service.py` (extraire la logique testee dans test_graph_api.py et test_reasoning_api.py qui deviennent des tests HTTP fins).
+
+---
+
+## Phase 3 — Decouplage frontend (B2) ≈ 2 jours
+
+### Strategie
+
+Deux options :
+
+**Option A — strict** : deplacer tous les composants partages vers `frontend/src/shared/ui/viewer/`.
+- Plus long, meilleur score audit, mais refactor important des chemins d'import.
+
+**Option B — pragmatique** : accepter `features/X/index.ts` comme "public API" d'une feature. Refuser uniquement les imports profonds (`features/X/ui/Y.vue`, `features/X/store`) depuis une autre feature.
+- Plus rapide, necessite d'ajouter une lint rule pour enforcer.
+
+**Recommande : mix A+B** :
+- Composants reellement partages par 3+ features -> `shared/ui/`.
+- Stores cross-feature -> remplacer par props au niveau page.
+- Import via `features/X/index.ts` accepte si strictement public API (pas de store).
+
+### Step 3.1 : Extraire styles reasoning du GraphView (casse le cycle)
+
+**Fichier** : `frontend/src/features/analysis/ui/GraphView.vue`
+
+```typescript
+// Supprimer :
+//   import { reasoningOverlayStyles } from '../../reasoning/graphReasoningOverlay'
+// Ajouter dans defineProps :
+const props = defineProps<{
+  // ... existants
+  extraStyles?: CytoscapeStyle[]  // Injected by parent feature (e.g. reasoning overlay)
+}>()
+// Dans la construction Cytoscape :
+const allStyles = [...baseStyles, ...(props.extraStyles ?? [])]
+```
+
+**Fichier** : `frontend/src/features/reasoning/ui/ReasoningWorkspace.vue`
+
+```typescript
+// Importer le style localement :
+import { reasoningOverlayStyles } from '../graphReasoningOverlay'
+// Passer au GraphView via prop :
+<GraphView ref="graphViewRef" :extra-styles="reasoningOverlayStyles" ... />
+```
+
+**Resultat** : le cycle `analysis <-> reasoning` est brise (reasoning depend d'analysis, pas l'inverse).
+
+### Step 3.2 : Deplacer les composants reellement partages vers `shared/ui/viewer/`
+
+Candidats (utilises par >= 2 features) :
+- `StructureViewer.vue` — utilise par `analysis` ET `reasoning`
+- `GraphView.vue` — utilise par `analysis` ET `reasoning`
+- `BboxOverlay.vue` — utilise par `analysis` (+ futur reasoning)
+
+Pas deplaces (utilises par 1 seul feature) :
+- `NodeDetailsPanel.vue`, `ResultTabs.vue`, `MarkdownViewer.vue`, `ImageGallery.vue` — specifique `analysis`
+- `AnalysisPanel.vue` — orchestrateur analysis, OK dans `features/analysis`
+
+**Migration** :
+```bash
+mkdir -p frontend/src/shared/ui/viewer
+git mv frontend/src/features/analysis/ui/StructureViewer.vue frontend/src/shared/ui/viewer/StructureViewer.vue
+git mv frontend/src/features/analysis/ui/GraphView.vue frontend/src/shared/ui/viewer/GraphView.vue
+git mv frontend/src/features/analysis/ui/BboxOverlay.vue frontend/src/shared/ui/viewer/BboxOverlay.vue
+```
+
+Mettre a jour les imports (14 fichiers environ). Utiliser l'alias `@/shared/ui/viewer/...`.
+
+**Fichier** : `frontend/src/features/analysis/index.ts` — supprimer les re-exports de StructureViewer/BboxOverlay.
+
+### Step 3.3 : `getPreviewUrl` vers `shared/api/documents.ts`
+
+**Nouveau fichier** : `frontend/src/shared/api/documents.ts`
+
+```typescript
+/** Preview URL for a document page (served by the backend). */
+export function getPreviewUrl(id: string, page = 1, dpi = 150): string {
+  return `/api/documents/${id}/preview?page=${page}&dpi=${dpi}`
+}
+```
+
+**Fichier** : `frontend/src/features/document/api.ts` — re-export pour compat interne mais consommer la version shared :
+```typescript
+export { getPreviewUrl } from '../../shared/api/documents'
+```
+
+**Fichier** : `frontend/src/features/analysis/ui/StructureViewer.vue` (devenu `shared/ui/viewer/`) et autres usages :
+```typescript
+import { getPreviewUrl } from '@/shared/api/documents'
+```
+
+### Step 3.4 : Eliminer les `useXxxStore` cross-feature
+
+Schema cible : les stores d'un feature ne sont accedes qu'a l'interieur de ce feature. Cross-feature -> props au niveau page.
+
+**Cas `chunking/ui/ChunkPanel.vue:228` -> `useAnalysisStore`** :
+- Ce dont a besoin ChunkPanel : l'analyse en cours (pour connaitre les chunks).
+- Fix : `StudioPage.vue` passe `:analysis="currentAnalysis"` a `<ChunkPanel>`.
+- `ChunkPanel` devient purement driven par props.
+
+**Cas `reasoning/ui/DocumentView.vue:34` -> `useAnalysisStore`** :
+- Besoin : les pages du document analyse.
+- Fix : passer `:pages="pages"` en prop (calcul au niveau `ReasoningWorkspace` ou `ReasoningPage`).
+
+**Cas `reasoning/ui/ReasoningDocPicker.vue:82-83` -> `useAnalysisStore`, `useDocumentStore`** :
+- Besoin : liste des documents + leur statut d'analyse.
+- Fix : creer un `useReasoningEligibleDocs()` composable dans `reasoning/` qui FETCH directement via API (pas de dependance au store d'un autre feature). Ou : passer la liste filtree en prop depuis la page.
+
+**Cas `analysis/ui/AnalysisPanel.vue:61` -> `useDocumentStore`** :
+- Besoin : le document courant et sa liste.
+- Fix : `AnalysisPanel` recoit `:documents`, `:selectedDocument` en props ; emits `@select-document`, `@upload-document`.
+
+**Cas `settings/ui/SettingsPanel.vue:70` -> `useFeatureFlagStore`** :
+- Feature-flags est transversal. Acceptable qu'un autre feature le lise.
+- Mais strict audit : exposer via `useFeatureFlag()` composable dans `shared/composables/` plutot que le store directement.
+
+**Fichier** : `frontend/src/shared/composables/useFeatureFlag.ts` (existe-t-il ? `grep` : oui, `frontend/src/features/feature-flags/useFeatureFlag.test.ts`). Deplacer le composable vers `shared/composables/` et laisser le store dans `features/feature-flags/`.
+
+### Step 3.5 : Lint rule (ESLint) pour prevenir regression
+
+**Fichier** : `frontend/eslint.config.js` (ou `.eslintrc`)
+
+```javascript
+{
+  files: ['src/features/**/*.{ts,vue}'],
+  rules: {
+    'no-restricted-imports': ['error', {
+      patterns: [
+        {
+          group: ['../../*/store', '../../*/ui/*', '../../*/api'],
+          message: 'Features must not import from other features. Use shared/ or props/events.',
+        },
+      ],
+    }],
+  },
+}
+```
+
+**Tests impactes** :
+- Tout test important `features/analysis/ui/StructureViewer.vue` a renommer en `shared/ui/viewer/StructureViewer.vue`.
+- `frontend/src/features/analysis/ui/StructureViewer.vue` existe-t-il comme fichier test ? Non, pas de `.test` pour les composants UI lourds (pattern du projet).
+
+**Risques** :
+- Casse des tests e2e Karate si les selecteurs `data-e2e` etaient dans les composants deplaces -> verifier (les selecteurs restent identiques si le composant n'est pas modifie, juste deplace).
+- HMR peut etre capricieux pendant la migration -> faire un vrai restart du dev server.
+
+---
+
+## Phase 4 — Cleanup (M5 + Q2-Q6) ≈ 0.5 jour
+
+### Step 4.1 : M5 — CHANGELOG `[Unreleased]`
+
+**Fichier** : `CHANGELOG.md`
+
+Ajouter entre la ligne 6 et 7 (`## [0.4.0]`) :
+
+```markdown
+## [Unreleased]
+
+### Added
+
+- Reasoning-trace viewer: import a `docling-agent` sidecar JSON and overlay RAG iterations on the document graph/PDF views
+- Live reasoning runner: `POST /api/documents/:id/rag` invokes `docling-agent`'s Chunkless RAG loop against a stored DoclingDocument (disabled by default via `RAG_ENABLED=false`; requires Ollama reachable + `docling-agent` and `mellea` installed)
+- Neo4j graph storage: DoclingDocument tree persisted via TreeWriter with Document/Element/Page/Provenance nodes; chunks persisted via ChunkWriter with DERIVED_FROM edges
+- Graph API endpoints: `GET /api/documents/:id/graph` (Neo4j-backed, full graph with chunks) and `GET /api/documents/:id/reasoning-graph` (SQLite-only, no Neo4j dep)
+- Frontend feature `reasoning/` with focus mode, iteration navigation, bidirectional graph/document sync
+- Env vars: `RAG_ENABLED`, `OLLAMA_HOST`, `RAG_MODEL_ID`, `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`, `MAX_GRAPH_PAGES`
+- Domain ports: `GraphWriter` (Neo4j-backed), `EmbeddingService`, `VectorStore`
+
+### Changed
+
+- Services no longer import `infra.neo4j` or `infra.serve_converter` directly — graph persistence goes through `GraphWriter` port; batching capability is exposed as `DocumentConverter.supports_batching` property (audit remediation 06-SOLID)
+- `StructureViewer`, `GraphView`, `BboxOverlay` moved to `frontend/src/shared/ui/viewer/` (audit remediation 07-decoupling)
+
+### Fixed
+
+- (a completer)
+```
+
+### Step 4.2 : Q5 — `.env.example` complet
+
+**Fichier** : `.env.example` (ajout en fin)
+
+```bash
+# --- Live reasoning (docling-agent runner) — disabled by default ---
+# RAG_ENABLED=false
+# OLLAMA_HOST=http://localhost:11434
+# RAG_MODEL_ID=gpt-oss:20b
+
+# --- Rate limiting (requests per minute per IP, 0 = disabled) ---
+# RATE_LIMIT_RPM=100
+
+# --- Timeouts (seconds) — must satisfy document < lock < conversion ---
+# DOCUMENT_TIMEOUT=120
+# LOCK_TIMEOUT=300
+# CONVERSION_TIMEOUT=900
+
+# --- Batch processing for very large PDFs (0 = disabled) ---
+# BATCH_PAGE_SIZE=0
+
+# --- OpenSearch max chunks returned per document ---
+# OPENSEARCH_DEFAULT_LIMIT=1000
+
+# --- Max pages per graph query (returns 413 beyond) ---
+# MAX_GRAPH_PAGES=200
+
+# --- Default table analysis mode: "accurate" or "fast" ---
+# DEFAULT_TABLE_MODE=accurate
+```
+
+### Step 4.3 : Q6 — Nginx cache statique
+
+**Fichier** : `nginx.conf` (inserer avant `location / {`)
+
+```nginx
+# Hashed assets (Vite emits content-hashed filenames) — cache 1 year
+location ~* \.(?:js|css|woff2?|ttf|otf|svg|png|jpg|jpeg|webp|gif|ico)$ {
+    expires 1y;
+    add_header Cache-Control "public, immutable";
+    try_files $uri =404;
+}
+```
+
+### Step 4.4 : Q2 — decouper les fonctions longues (non bloquant, best effort)
+
+**Cibles prioritaires** (ordre de gain pedagogique) :
+1. `infra/neo4j/tree_writer.py:67` `write_document` (228L) — decouper en :
+   - `_wipe_existing(tx, doc_id)`
+   - `_write_document_node(tx, doc_id, filename, ...)`
+   - `_write_pages(tx, doc_id, pages)`
+   - `_write_elements_and_provenances(tx, ...)`
+   - `_write_structural_edges(tx, ...)`
+2. `infra/neo4j/queries.py:143` `fetch_graph` (126L) — une helper par groupe de nodes/edges.
+3. Si le refactor Phase 2 a bien fait son job, `api/reasoning.py:run_rag` et `api/graph.py:get_reasoning_graph` sont deja < 30L.
+
+### Step 4.5 : Q3 — signatures avec dataclass context
+
+**Fichier** : `document-parser/services/analysis_service.py`
+
+```python
+@dataclass
+class AnalysisContext:
+    job_id: str
+    file_path: str
+    filename: str
+    pipeline_options: dict | None = None
+    chunking_options: dict | None = None
+
+# Remplacer :
+#   async def _run_analysis(self, job_id, file_path, filename, pipeline_options, chunking_options)
+# par :
+#   async def _run_analysis(self, ctx: AnalysisContext)
+```
+
+**Fichier** : `document-parser/domain/models.py`
+
+```python
+@dataclass
+class CompletionPayload:
+    markdown: str
+    html: str
+    pages_json: str
+    document_json: str | None = None
+    chunks_json: str | None = None
+
+# Sur AnalysisJob :
+def mark_completed(self, payload: CompletionPayload) -> None:
+    ...
+```
+
+### Step 4.6 : Q4 — splitter les gros composants Vue (planification)
+
+Hors scope immediate — trop gros pour la fenetre 0.5.0. **Acter en dette** :
+- `StudioPage.vue` (1450L) : a decouper en `StudioUploadSection.vue`, `StudioAnalysisSection.vue`, `StudioResultsSection.vue` en 0.6.
+- `ChunkPanel.vue` (801L), `GraphView.vue` (695L), `ResultTabs.vue` (690L) : ticket dedie post-0.5.
+
+---
+
+## Re-audit delta apres remediations
+
+Apres P1 + P2 + P3 + P4, **re-lancer uniquement** :
+
+| Audit | Raison |
+|-------|--------|
+| 01 Hexa Arch | Verifier que M1 (graph+reasoning services) a elimine le MAJ |
+| 03 Clean Code | Verifier run_rag < 30L et SRP ok |
+| 05 DRY | Verifier MAX_PAGES purge |
+| 06 SOLID | Verifier CRIT B1 resolu + MAJ M4 resolu |
+| 07 Decouplage | Verifier CRIT B2 resolu (grep imports cross-feature hors `shared/`) |
+| 10 CI/Build | Verifier `.env.example` complet |
+| 11 Documentation | Verifier CHANGELOG + version bump |
+
+Audits **02, 04, 08, 09, 12** : pas de changement attendu, on peut les skipper au re-audit.
+
+Commande :
+```
+Re-audite uniquement les audits 01, 03, 05, 06, 07, 10, 11 sur la branche courante en suivant docs/audit/master.md
+```
+
+---
+
+## Ordonnancement git/PR recommande
+
+| PR | Branche | Contenu | Audits concernes |
+|----|---------|---------|------------------|
+| PR-A | `fix/0.5.0-port-graphwriter` | Phase 1 (B1 + M4) | 06 |
+| PR-B | `fix/0.5.0-extract-services` | Phase 2 (M1 + M2 + M3 + Q1) | 01, 03, 05 |
+| PR-C | `fix/0.5.0-frontend-decoupling` | Phase 3 (B2) | 07 |
+| PR-D | `chore/0.5.0-release-prep` | Phase 4 (M5 + Q5 + Q6 + Q2 + Q3) | 10, 11 |
+
+Chaque PR doit rester petit (revue + CI courte). Base : toutes branchees sur `release/0.5.0` cree depuis `feature/reasoning-trace` (en suivant la convention git flow du projet).
+
+---
+
+## Estimation globale
+
+| Phase | Duree | Effort (dev-jour) |
+|-------|-------|-------------------|
+| 1 — Ports | 1j | 1 |
+| 2 — Services | 1.5j | 1.5 |
+| 3 — Frontend | 2j | 2 |
+| 4 — Cleanup | 0.5j | 0.5 |
+| **Total** | **5j** | **5 dev-jour** |
+
+Avec 2 devs en parallele (un backend PR-A+B, un frontend PR-C+D), **3 jours calendaires** suffisent.
+
+---
+
+## Validation finale avant tag 0.5.0
+
+- [ ] PR-A, B, C, D mergees dans `release/0.5.0`
+- [ ] `ruff check . && ruff format --check .` vert
+- [ ] `pytest tests/ -v` vert (backend)
+- [ ] `npm run lint && npm run type-check && npm run test:run` vert (frontend)
+- [ ] `npm run build` produit un bundle sans warning
+- [ ] CI GitHub Actions verte sur `release/0.5.0`
+- [ ] Re-audit delta ci-dessus repasse GO (CRIT = 0, MAJ <= 3)
+- [ ] `CHANGELOG.md` : renommer `[Unreleased]` en `[0.5.0] - 2026-04-XX`
+- [ ] `frontend/package.json` : bump `"version": "0.5.0"`
+- [ ] Tag git `v0.5.0` sur `release/0.5.0`

docs/audit/reports/release-0.5.0/summary-reaudit.md

@@ -0,0 +1,107 @@
+# Re-audit ciblé — Release 0.5.0
+
+**Date** : 2026-04-29
+**Branche** : `fix/release-0.5.0-audit-remediation` (off `release/0.5.0`)
+**Périmètre** : tous les écarts CRITICAL et MAJOR du `summary.md` initial (regle master §7).
+**Auditeur** : claude-code
+
+---
+
+## Tableau de bord — avant / après
+
+| #  | Audit                | Score initial | CRIT initial | MAJ initial | Score post-remédiation | CRIT | MAJ | Verdict |
+|----|----------------------|--------------:|-------------:|------------:|-----------------------:|-----:|----:|---------|
+| 01 | Clean Architecture   | 100           | 0            | 0           | **100**                | 0    | 0   | GO      |
+| 02 | DDD                  | 91            | 0            | 1           | **~95**                | 0    | 0   | GO      |
+| 03 | Clean Code           | 83            | 0            | 0           | 83 *(inchangé)*        | 0    | 0   | GO      |
+| 04 | KISS                 | 87.5          | 0            | 0           | 87.5 *(inchangé)*      | 0    | 0   | GO      |
+| 05 | DRY                  | 71            | 0            | 2           | **~88**                | 0    | 0   | GO      |
+| 06 | SOLID                | 85            | 0            | 1           | **~95**                | 0    | 0   | GO      |
+| 07 | Découplage           | 86            | 0            | 1           | **~93**                | 0    | 0   | GO      |
+| 08 | Sécurité             | 91            | 0            | 2           | **~98**                | 0    | 0   | GO      |
+| 09 | Tests                | 94            | 0            | 1           | **~97**                | 0    | 0   | GO      |
+| 10 | CI / Build           | 91            | 0            | 1           | **~96**                | 0    | 0   | GO      |
+| 11 | Documentation        | **44**        | **1**        | 2           | **100**                | 0    | 0   | GO      |
+| 12 | Performance          | 86.67         | 0            | 1           | **~93**                | 0    | 0   | GO      |
+
+**Score global (moyenne simple)** : **84.2 → ~94/100**
+**CRIT totaux** : 1 → **0**
+**MAJ totaux** : 12 → **0**
+
+---
+
+## Vérification item par item
+
+### CRITICAL (1)
+
+| # | Item | Statut | Preuve |
+|---|------|--------|--------|
+| 11.CRIT | `CHANGELOG.md` sans section `[0.5.0]` | ✅ Résolu | [CHANGELOG.md:7](CHANGELOG.md:7) — `## [0.5.0] - 2026-04-28` |
+
+### MAJOR (12)
+
+| # | Item | Statut | Preuve |
+|---|------|--------|--------|
+| 11.MAJ.1 | `frontend/package.json` à `0.4.0` | ✅ Résolu | [frontend/package.json:3](frontend/package.json:3) — `"version": "0.5.0"` |
+| 11.MAJ.2 | Modifications 0.5.0 non documentées | ✅ Résolu | CHANGELOG `[0.5.0]` détaille Added / Changed / Fixed |
+| 08.MAJ.1 | Mot de passe Neo4j `changeme` | ✅ Résolu (cadrage dev) | [docker-compose.yml:1-26](docker-compose.yml:1) — header dev-only ; [main.py:104-110](document-parser/main.py:104) — warning au boot si `NEO4J_URI` set + password=`changeme` |
+| 08.MAJ.2 | OpenSearch `DISABLE_SECURITY_PLUGIN=true` | ✅ Résolu (cadrage dev) | [docker-compose.yml:47-52](docker-compose.yml:47) — commentaire "DEV ONLY" + lien doc OpenSearch |
+| 05.MAJ.1 | URL d'API hardcodée frontend | ✅ Résolu | `apiUrl` était du code mort → suppression du ref + des i18n keys orphelines (`settings.apiUrl`) |
+| 05.MAJ.2 | Clés `localStorage` dispersées | ✅ Résolu | [frontend/src/shared/storage/keys.ts](frontend/src/shared/storage/keys.ts) — `STORAGE_KEYS` ; [features/settings/store.ts](frontend/src/features/settings/store.ts) consomme |
+| 02.MAJ | Ubiquitous language `job` ↔ `analysis` | ✅ Résolu | Path params `{job_id}` → `{analysis_id}` dans [api/analyses.py](document-parser/api/analyses.py) + [api/ingestion.py](document-parser/api/ingestion.py) (URLs identiques côté client) |
+| 06.MAJ | LSP — `isinstance(ServeConverter)` | ✅ Résolu | [domain/ports.py:DocumentConverter](document-parser/domain/ports.py) — `supports_page_batching: bool` exposé via le port ; [services/analysis_service.py:340](document-parser/services/analysis_service.py:340) lit le port |
+| 07.MAJ | Couplage inter-feature dans tests | ✅ Résolu | Test déplacé : [frontend/src/__tests__/integration/history-navigation.test.ts](frontend/src/__tests__/integration/history-navigation.test.ts) ; les feature folders restent self-contained |
+| 09.MAJ | 18 assertions vagues `assert X is not None` | ✅ Résolu | 8 assertions vraiment terminales resserrées (`isinstance(.., datetime)`, comparaisons exactes) ; les 10 restantes sont des type-narrowings légitimes suivis d'assertions sur la valeur |
+| 10.MAJ | Ruff UP038 (`isinstance` union syntax) | ✅ Résolu | [infra/docling_tree.py:101](document-parser/infra/docling_tree.py:101) — `list \| tuple` ; `ruff check` passe (0 erreurs) |
+| 12.MAJ | I/O sync dans endpoint async | ✅ Résolu | [api/documents.py:119-122](document-parser/api/documents.py:119) — `Path(...).read_bytes` et `generate_preview` wrappés dans `asyncio.to_thread` |
+
+---
+
+## Renforcements indirects (volet 1 — reasoning)
+
+Au-delà des écarts ciblés, la refacto reasoning consolide plusieurs audits :
+
+- **01 Clean Architecture** : confirmation `grep -rE "^from docling_agent|^from docling_core|^from mellea" api/ domain/ services/` → **0 résultat**. Couplage upstream confiné à `infra/docling_agent_reasoning.py` + `infra/llm/ollama_provider.py`.
+- **06 SOLID — DIP** : `api/reasoning.py` consomme un port `ReasoningRunner` ; aucune classe concrète importée dans la couche API.
+- **07 Découplage** : un seul point de couplage à la lib upstream (l'adapter). Le `_rag_loop` privé est encapsulé + tracé via [docling-agent#26](https://github.com/docling-project/docling-agent/issues/26).
+- **08 Sécurité** : la mutation `os.environ["OLLAMA_HOST"]` par requête (race) est éliminée — l'adapter commit le host **une fois** au boot.
+- **09 Tests** : +17 tests adaptés (`test_docling_agent_reasoning.py`, `test_ollama_provider.py`), incluant un test d'isolation concurrence (R3).
+
+---
+
+## Items MIN / INFO restants (non-bloquants, planifiés 0.5.1+)
+
+| # | Origine | Item | Plan |
+|---|---------|------|------|
+| 03.MIN.1 | Clean Code | `StudioPage.vue` (~1450L), `ChunkPanel.vue` (~801L), `ResultTabs.vue` (~690L) | Bloc E — découper en sous-composants en 0.5.1 |
+| 03.MIN.2 | Clean Code | 3 fonctions > 30 lignes / 4 fonctions > 4 paramètres | Bloc E — décomposition locale en 0.5.1 |
+| 04.MIN | KISS | Wrapper `_to_response`, accessors redondants `DocumentService` | Bloc F — arbitrage en 0.5.1 |
+| 05.MIN | DRY | Magic string [api/schemas.py:54](document-parser/api/schemas.py:54) | ✅ Résolu — `DOCUMENT_STATUS_UPLOADED` |
+| 04.INFO | KISS | Polling `setInterval/setTimeout` imbriqués | Bloc F |
+| 04.INFO | KISS | Overhead `DocumentConfig` / `IngestionConfig` dataclasses | Bloc F |
+| 08.INFO | Sécurité | Default LOG_LEVEL non-borné | Sera traité avec la prochaine vague observabilité |
+| 12.INFO | Performance | `find_all` implicite (pas de pagination forte) | Bloc E (split graph endpoint) en 0.5.1 |
+
+---
+
+## Verdict final post-remédiation : **GO** ✅
+
+**Justification** :
+- Zéro écart CRITICAL (la règle absolue du master §3 est levée).
+- Zéro écart MAJOR — tous les MAJ initiaux sont résolus.
+- Score global ~94/100 ≥ 80 (seuil GO).
+- Tous les audits individuels passent en GO.
+- La pipeline de validation est verte : ruff + format + 446 pytest backend, ESLint + Prettier + vue-tsc + 202 vitest frontend.
+
+**Conditions tenues** :
+1. ✅ CHANGELOG `[0.5.0]` complet
+2. ✅ `frontend/package.json` à `0.5.0`
+3. ✅ Sécurité dev-only documentée + warning au boot sur `changeme`
+4. ✅ DRY frontend (storage keys + dead apiUrl supprimé)
+5. ✅ Refacto archi reasoning (port + adapter + DI) — bonus volet 1
+
+**Reste planifié hors release 0.5.0** :
+- Bloc E (découpage Vue files volumineux + signatures de fonctions back) → 0.5.1
+- Bloc F (KISS micro-optimisations + INFO) → 0.5.1
+
+La release **0.5.0 peut être taguée** depuis `release/0.5.0` une fois la branche `fix/release-0.5.0-audit-remediation` mergée.

docs/audit/reports/release-0.5.0/summary.md

@@ -0,0 +1,106 @@
+# Synthese d'audit — Release 0.5.0
+
+**Date** : 2026-04-28
+**Branche** : `release/0.5.0`
+**Commit audite** : `b2e0af3`
+**Auditeur** : claude-code
+
+---
+
+## Tableau de bord
+
+| #  | Audit                | Score   | CRIT | MAJ | MIN | INFO | Verdict          |
+|----|----------------------|---------|------|-----|-----|------|------------------|
+| 01 | Clean Architecture   | 100     | 0    | 0   | 0   | 0    | GO               |
+| 02 | DDD                  | 91      | 0    | 1   | 1   | 0    | GO               |
+| 03 | Clean Code           | 83      | 0    | 0   | 3   | 0    | GO               |
+| 04 | KISS                 | 87.5    | 0    | 0   | 1   | 2    | GO               |
+| 05 | DRY                  | 71      | 0    | 2   | 1   | 2    | GO CONDITIONNEL  |
+| 06 | SOLID                | 85      | 0    | 1   | 1   | 0    | GO               |
+| 07 | Decouplage           | 86      | 0    | 1   | 1   | 0    | GO CONDITIONNEL  |
+| 08 | Securite             | 91      | 0    | 2   | 0   | 1    | GO CONDITIONNEL  |
+| 09 | Tests                | 94      | 0    | 1   | 0   | 0    | GO               |
+| 10 | CI / Build           | 91      | 0    | 1   | 0   | 0    | GO CONDITIONNEL  |
+| 11 | Documentation        | **44**  | **1**| 2   | 0   | 0    | **NO-GO**        |
+| 12 | Performance          | 86.67   | 0    | 1   | 1   | 1    | GO CONDITIONNEL  |
+
+**Score global (moyenne simple)** : **84.2 / 100**
+**Ecarts CRITICAL totaux** : **1**
+**Ecarts MAJOR totaux** : **12**
+**Ecarts MINOR totaux** : 8
+**Ecarts INFO totaux** : 6
+
+---
+
+## Ecarts CRITICAL (tous audits confondus)
+
+1. **[11] CHANGELOG.md sans section `[0.5.0]`** — `CHANGELOG.md:7`
+   La derniere section listee est `## [0.4.0] - 2026-04-13`. Aucune entree `[Unreleased]` ni `[0.5.0]`. Tagger 0.5.0 depuis ce HEAD livrerait un changelog mensonger qui omet les nouveautes de la release (reasoning-trace viewer, Neo4j graph storage, RAG endpoints, feature flags). **Bloquant absolu** par regle master §3.
+
+---
+
+## Top blockers (poids 3 / poids 2)
+
+### Bloquant (poids 3)
+
+- **[11] CHANGELOG sans section 0.5.0** — `CHANGELOG.md:7`
+  Ajouter `## [0.5.0] - 2026-04-28` avec sous-sections `Added` / `Changed` / `Fixed` listant les changements depuis 0.4.0.
+
+### Majeurs (poids 2) — a remediar pour passer a GO
+
+- **[11] `frontend/package.json` toujours a `0.4.0`** — `frontend/package.json:3`
+  Bumper a `"version": "0.5.0"`.
+- **[11] Modifications de la release 0.5.0 non documentees** — `CHANGELOG.md`
+  Resolu en meme temps que le CRIT.
+- **[08] Mot de passe Neo4j par defaut `"changeme"`** — `document-parser/infra/settings.py:30,133`
+  Forcer la lecture d'une variable d'environnement, supprimer le defaut, faire echouer le boot si absent en prod.
+- **[08] OpenSearch security plugin desactive** — `docker-compose.yml:26`
+  `DISABLE_SECURITY_PLUGIN=true` doit etre off pour tout deploiement non-dev ; documenter explicitement le perimetre.
+- **[05] URL d'API hardcodee en frontend** — `frontend/src/features/settings/store.ts:23`
+  Centraliser dans une constante `API_BASE_URL` lue depuis `import.meta.env`.
+- **[05] Cles localStorage en clair, dispersees** — `frontend/src/features/settings/store.ts:24-27`
+  Centraliser dans une enum/objet `STORAGE_KEYS`.
+- **[02] Ubiquitous language "job" vs "analysis"** — `document-parser/api/ingestion.py:49-67`
+  Aligner le vocabulaire HTTP sur le langage du domaine.
+- **[06] LSP — `isinstance()` sur adaptateur** — `document-parser/services/analysis_service.py:356`
+  Supprimer le check de type concret ou exposer la capacite via le port.
+- **[07] Couplage inter-feature dans les tests** — `frontend/src/features/history/navigation.test.ts:30-31,67,82-83,143-144,169-170,188`
+  Stubber les stores via injection au lieu d'imports directs.
+- **[09] Assertions vagues `assert X is not None`** — 18 occurrences en backend
+  Ajouter une assertion sur la valeur attendue, pas seulement sur la presence.
+- **[10] Ruff UP038 — syntaxe `isinstance()` union** — `document-parser/infra/docling_tree.py:101`
+  Appliquer la suggestion pyupgrade.
+- **[12] I/O synchrone dans endpoint async** — `document-parser/api/documents.py:115-116`
+  Wrapper l'acces fichier dans `asyncio.to_thread(...)` pour ne pas bloquer la loop FastAPI.
+
+---
+
+## Quick wins (poids 1 — ameliorations rapides)
+
+- **[03] Trois fichiers Vue > 300 lignes** — `frontend/src/views/StudioPage.vue` (~1450L), `frontend/src/.../ChunkPanel.vue` (~801L), `frontend/src/.../ResultTabs.vue` (~690L). Extraire des sous-composants.
+- **[03] Fonctions > 30 lignes** (3 cas) et **fonctions > 4 parametres** (4 cas). Decoupage local.
+- **[04] Wrapper trivial `_to_response`** — utiliser `Pydantic.model_validate()` directement.
+- **[04] Accessors redondants dans `DocumentService`**.
+- **[05] Magic string isolee** — `document-parser/api/schemas.py:49`.
+- **[12] Polling avec setInterval/setTimeout imbriques** — `frontend/src/features/settings/store.ts:27-39` et store analysis.
+
+---
+
+## Verdict final : **NO-GO**
+
+**Justification** : 1 ecart CRITICAL non resolu dans l'audit 11 (Documentation) → regle absolue du master.md §3 : `tout ecart [CRIT] non resolu = NO-GO quel que soit le score`.
+
+Bien que le score global (84.2/100) soit confortablement au-dessus du seuil GO et que 11 audits sur 12 soient au moins en GO CONDITIONNEL, le release 0.5.0 **ne peut pas etre tague** dans cet etat.
+
+### Conditions pour passer a GO
+
+**Bloquant absolu** (1 action) :
+1. Ajouter la section `## [0.5.0] - 2026-04-28` dans `CHANGELOG.md` avec `Added` / `Changed` / `Fixed`.
+
+**Pour passer de GO CONDITIONNEL a GO** (4 actions, ~30 min) :
+2. Bumper `frontend/package.json` a `0.5.0`.
+3. Remplacer `"changeme"` par lecture d'env var obligatoire (`document-parser/infra/settings.py`).
+4. Documenter / corriger la desactivation du security plugin OpenSearch (`docker-compose.yml`).
+5. Centraliser l'URL d'API et les cles localStorage du frontend (`frontend/src/features/settings/store.ts`).
+
+**Recommandation** : apres remediation des 5 points ci-dessus, re-auditer **uniquement** les audits 11, 08 et 05 (commande : `Re-audite uniquement les ecarts CRITICAL et MAJOR du rapport docs/audit/reports/release-0.5.0/summary.md`). Les autres MAJ peuvent etre planifies pour 0.5.1 sans bloquer le tag.

docs/design/195-copy-paste-image-verify-mode.md

@@ -0,0 +1,404 @@
+# Design: Copy paste image in Verify mode
+
+<!--
+Design doc template for Docling Studio.
+
+One design doc per tracked issue. File path convention:
+  docs/design/<issue-number>-<kebab-slug>.md
+
+Status lifecycle: Draft → In review → Accepted → Implemented (or Superseded).
+Bump the Status line as the doc progresses; do not delete sections on the way.
+
+This template is tailored to the project's architecture and conventions:
+  - Backend Hexagonal Architecture / ports & adapters
+    (domain → api/services/persistence/infra)
+    see docs/architecture.md
+  - Backend coding standards (FastAPI + Pydantic camelCase, aiosqlite,
+    Python snake_case internal, max 300 lines/file, 30 lines/function)
+    see docs/architecture/coding-standards.md
+  - Frontend feature-based organization (Vue 3 + Pinia, one store per
+    feature, Composition API, TypeScript strict, data-e2e selectors)
+  - E2E with Karate UI (NOT Playwright) — see e2e/CONVENTIONS.md
+  - Audit dimensions used at release gate — see docs/audit/master.md
+  - ADR process for load-bearing decisions — see docs/architecture/adr-guide.md
+
+The `/conception` command pre-fills the header block and §1 / §2 / §12 from
+the linked issue. Everything else is on the author.
+-->
+
+- **Issue:** #195
+- **Title on issue:** [ENHANCEMENT] Copy paste image in Verify mode
+- **Author:** Pier-Jean Malandrino
+- **Date:** 2026-04-23
+- **Status:** Accepted
+- **Target milestone:** 0.5.0
+- **Impacted layers:** <backend: domain | api | services | persistence | infra> · <frontend: features/<name> | shared | app> · <e2e> · <infra/CI>
+- **Audit dimensions likely touched:** <pick from: Hexagonal Architecture · DDD · Clean Code · KISS · DRY · SOLID · Decoupling · Security · Tests · CI/Build · Documentation · Performance>
+- **ADR spawned?:** <no>  *(write an ADR when choosing a library, moving a boundary, or deciding **not** to do something — see `docs/architecture/adr-guide.md`)*
+
+---
+
+## 1. Problem
+
+<!--
+What hurts today, and for whom. Pull from the issue's Context + Current
+behavior sections — keep the user's voice, do not paraphrase aggressively.
+Two or three short paragraphs is usually enough. If you can't state the
+problem in plain language, you are not ready to design a solution.
+-->
+
+TODO: Why this issue exists. Link the user story, incident, or upstream discussion that motivates it.
+
+Today in Verify mode regarding image handling: TODO — describe the current baseline (upload-only? no paste target? no drag-drop?).
+
+## 2. Goals
+
+<!--
+Concrete, verifiable outcomes. Convert the issue's acceptance criteria into
+checkboxes here; the design is "done" when all are satisfied. Keep the list
+small — five or fewer goals is a good smell.
+-->
+
+Users should be able to copy/paste images directly into Verify mode (e.g. from clipboard) instead of only via file upload.
+
+- [ ] Define paste source (OS clipboard, drag-drop, screenshot)
+- [ ] Define target area in Verify mode UI
+- [ ] Define supported image formats and size limits
+- [ ] Size / type limits are env-var configurable, carry sane defaults, and are documented in `README.md` + `docs/deployment/*` (e.g. `MAX_PASTE_IMAGE_SIZE_MB`, `PASTE_ALLOWED_IMAGE_TYPES`)
+
+## 3. Non-goals
+
+<!--
+What this design explicitly does NOT try to solve — and, for each, where it
+*should* be solved (follow-up issue, next milestone, different audit area).
+This is the section that saves the review: naming the off-ramps up front
+prevents scope creep. If you leave this empty, reviewers will fill it in
+for you, badly.
+-->
+
+- ...
+- ...
+
+## 4. Context & constraints
+
+<!--
+The surrounding reality the design has to live in.
+
+### Existing code surface
+List the modules / files / stores this change touches. Prefer concrete paths
+over prose:
+  - Backend: document-parser/<layer>/<file>.py
+  - Frontend: frontend/src/features/<name>/{store,api,ui}.ts|.vue
+  - Persistence: document-parser/persistence/<repo>.py + schema in database.py
+  - E2E: e2e/<feature>.feature
+
+### Hexagonal Architecture constraints (backend)
+The domain layer has zero imports from api / persistence / infra, and
+defines ports (abstract protocols) that `infra/` adapters implement.
+Persistence imports only from domain. API never imports persistence
+directly — it goes through services. Call out any change that crosses
+these lines or adds / moves a port.
+
+### Deployment modes
+Docling Studio ships two images (`latest-local`, `latest-remote`) driven by
+`CONVERSION_ENGINE` — and a HF Space deployment on top of `latest-remote`.
+State which modes this design supports, which it does not, and how the
+frontend's feature flags (`chunking`, `disclaimer`) are affected.
+
+### Hard constraints
+Compatibility (SQLite schema, API contract, Pydantic DTOs), deadlines
+(milestone due date), deployment target (Docker Compose, HF Space),
+performance budget (matters for Performance audit), license / privacy
+(matters for Security audit).
+-->
+
+### SQLite & storage limits (must be enforced upstream of the DB)
+
+Pasted images follow the existing `documents` pattern: bytes land on disk
+under `UPLOAD_DIR`, the row stores `storage_path: TEXT`. We do **not**
+store base64 or BLOBs. Even so, app-level size guards must stay below
+SQLite's structural limits so a malformed request can never wedge the
+engine.
+
+Relevant SQLite defaults (see https://www.sqlite.org/limits.html):
+
+| SQLite limit | Default | Relevance |
+|---|---|---|
+| `SQLITE_MAX_LENGTH` | 1 GB (1 × 10⁹ bytes) | Max size of any single `TEXT` / `BLOB` cell. Irrelevant as long as we keep bytes off the DB. |
+| `SQLITE_MAX_SQL_LENGTH` | 1 MB | Max length of an SQL statement incl. inlined literals. Always use parameter binding — never inline image bytes. |
+| Page cache / WAL growth | n/a | Large writes bloat WAL until checkpoint; another reason to stay off-DB. |
+
+Our own app-level limits guard against ever reaching those ceilings.
+All such limits **must**: (1) carry a sane default in `infra/settings.py`,
+(2) be overridable via env var, (3) be documented in `README.md` and
+`docs/deployment/*`. This is consistent with how `MAX_FILE_SIZE_MB`
+(default 50) is handled today.
+
+## 5. Proposed design
+
+<!--
+The recommended approach, in enough detail that a competent engineer
+outside the immediate context can implement it. Describe contracts, not
+code — the PR is where code lives.
+
+Structure this section by layer. Skip a layer if it is genuinely untouched;
+do not pad.
+
+### 5.1 Domain
+New or changed dataclasses / value objects / ports in `document-parser/domain/`.
+No HTTP or DB concerns here. If you are adding a port (`Protocol`), give its
+full signature.
+
+### 5.2 Persistence
+Schema changes (table, columns, indexes), migration plan, aiosqlite query
+shape. Note whether existing rows need a backfill.
+
+### 5.3 Infra adapters
+New or changed adapters in `document-parser/infra/` (converter, chunker,
+rate limiter, settings). For new env vars, give name / default / allowed
+values.
+
+### 5.4 Services
+Use-case orchestration in `document-parser/services/`. Services do NOT
+implement — they delegate. Describe the call sequence, error handling,
+and concurrency (how does this interact with `MAX_CONCURRENT_ANALYSES`?).
+
+### 5.5 API
+Endpoint additions / changes in `document-parser/api/`. For each:
+  - Method + path
+  - Request DTO (Pydantic, camelCase via alias_generator)
+  - Response DTO (camelCase; remember `pages_json` stays snake_case)
+  - Error responses (status codes, shape)
+  - Whether it is excluded from the rate limiter (like `/api/health`)
+
+### 5.6 Frontend — feature module
+Which `frontend/src/features/<name>/` folder, which Pinia store actions,
+which API client calls in `api.ts`, which Vue components in `ui/`. Name
+new `data-e2e` attributes here (Karate needs them).
+
+### 5.7 Cross-cutting
+Feature flags (how the backend advertises capability via `/api/health` and
+how the frontend reacts), i18n strings (`shared/i18n.ts`), shared types
+(`shared/types.ts`).
+
+Prefer mermaid / ASCII for sequence and data flow. Interfaces are more
+valuable than pseudocode.
+-->
+
+### 5.1 Domain
+
+### 5.2 Persistence
+
+### 5.3 Infra adapters
+
+Extend `document-parser/infra/settings.py` with paste-specific limits.
+Follow the existing `MAX_FILE_SIZE_MB` pattern: typed field on the
+settings dataclass, `os.environ.get(...)` with a string default, cast
+at load time.
+
+| Setting | Env var | Default | Allowed | Notes |
+|---|---|---|---|---|
+| `max_paste_image_size_mb` | `MAX_PASTE_IMAGE_SIZE_MB` | `10` | positive int, `0` = unlimited | Must be ≤ `MAX_FILE_SIZE_MB`; upload validator rejects larger payloads before any DB write. |
+| `paste_allowed_image_types` | `PASTE_ALLOWED_IMAGE_TYPES` | `image/png,image/jpeg,image/webp` | comma-separated MIME list | Enforced server-side; frontend uses the same list via `/api/health`. |
+
+Validation happens in the API layer (upload handler) **before** the
+bytes reach persistence. Any future move to BLOB storage would still
+rely on these guards — they are the contract that prevents us ever
+approaching `SQLITE_MAX_LENGTH`.
+
+### 5.4 Services
+
+### 5.5 API
+
+### 5.6 Frontend — feature module
+
+### 5.7 Cross-cutting (feature flags, i18n, shared types)
+
+## 6. Alternatives considered
+
+<!--
+At least two genuine alternatives, each with a one-paragraph description
+and the reason it was rejected. "Do nothing" is often a legitimate
+alternative — name it if it is. Reviewers use this section to sanity-check
+that the recommended design was a choice and not the first thing that
+came to mind.
+
+If one of the alternatives represents a significant architectural fork
+(e.g. introducing a new service, replacing a library), spawn an ADR under
+`docs/architecture/adrs/` and link it in §12 — the design doc captures the
+local decision, the ADR captures the cross-cutting one.
+-->
+
+### Alternative A — <name>
+
+- **Summary:**
+- **Why not:**
+
+### Alternative B — <name>
+
+- **Summary:**
+- **Why not:**
+
+## 7. API & data contract
+
+<!--
+Make the wire contract explicit — this is what the frontend, e2e tests,
+and any external consumer will code against.
+
+### Endpoints
+| Method | Path | Request | Response | Breaking? |
+|--------|------|---------|----------|-----------|
+|        |      |         |          |           |
+
+Remember:
+  - API serialization is camelCase (Pydantic `alias_generator`).
+  - Backend internals stay snake_case.
+  - `pages_json` is the documented exception — it carries raw
+    `dataclasses.asdict()` output (snake_case).
+  - Health endpoint (`/api/health`) may need new fields if this design adds
+    a feature flag.
+
+### Persistence schema
+```sql
+-- ALTER TABLE / CREATE TABLE statements, with reasoning
+```
+
+### Env vars / config
+
+All new knobs must land in `README.md` and `docs/deployment/*` (same
+tables that already list `MAX_FILE_SIZE_MB`, `UPLOAD_DIR`, etc.).
+
+| Name | Default | Allowed | Notes |
+|------|---------|---------|-------|
+| `MAX_PASTE_IMAGE_SIZE_MB` | `10` | positive int (`0` = unlimited) | Guards app-level payload size; must stay ≤ `MAX_FILE_SIZE_MB` to avoid double-gating confusion. |
+| `PASTE_ALLOWED_IMAGE_TYPES` | `image/png,image/jpeg,image/webp` | comma-separated MIME list | Surfaced to the frontend via `/api/health` so the paste handler can reject client-side. |
+
+SQLite ceilings (`SQLITE_MAX_LENGTH` = 1 GB, `SQLITE_MAX_SQL_LENGTH` =
+1 MB) are **not** env-configurable — they are compile-time properties
+of the bundled engine. Document them in `docs/deployment/*` as
+background so operators understand why the app-level limits exist.
+
+### Breaking changes
+Enumerate anything a consumer must change. If there are none, say so
+explicitly — "additive only" is a useful commitment.
+-->
+
+## 8. Risks & mitigations
+
+<!--
+One row per non-trivial risk. Map each to an audit dimension so the
+release-gate audit has a clear hook:
+
+| Risk | Audit dimension | Likelihood | Impact | How we notice | Mitigation / rollback |
+|------|-----------------|-----------|--------|---------------|------------------------|
+|      | Security        |           |        |               |                        |
+|      | Performance     |           |        |               |                        |
+|      | Decoupling      |           |        |               |                        |
+
+Common families to scan for:
+  - **Hexagonal Architecture:** cross-layer imports, leaking HTTP into domain, adapter bypassing its port
+  - **Security:** rate limiter bypass, path traversal on uploads, SSRF via
+    the remote converter, unauthenticated data exposure
+  - **Performance:** synchronous work on the FastAPI event loop,
+    unbounded queries, new work inside `MAX_CONCURRENT_ANALYSES` budget
+  - **Tests:** coverage gap on a critical path
+  - **Documentation:** missing README / env var / i18n entry
+
+A design with "no risks identified" is a design that has not been read
+carefully.
+-->
+
+| Risk | Audit dimension | Likelihood | Impact | How we notice | Mitigation / rollback |
+|------|-----------------|------------|--------|---------------|------------------------|
+|      |                 |            |        |               |                        |
+
+## 9. Testing strategy
+
+<!--
+How this design will be verified. Be specific — name files / suites.
+
+### Backend — pytest (`document-parser/tests/`)
+  - Unit: per-layer (`tests/domain/`, `tests/persistence/`, `tests/services/`)
+  - Integration: services wired with real aiosqlite + real adapters
+  - Architecture tests (if applicable): enforce import boundaries
+
+### Frontend — Vitest (`frontend/src/**/*.test.ts`)
+  - Stores: actions / getters / mocked API
+  - Pure helpers (e.g. `bboxScaling.ts`-style modules): deterministic
+  - Components only when behavior is non-trivial; do not test markup
+
+### E2E — Karate UI (`e2e/`)
+  - Use `data-e2e` selectors — never CSS classes (see e2e/CONVENTIONS.md)
+  - `retry()` / `waitFor()` — never `Thread.sleep()` / `delay()`
+  - Setup via API, verify via UI, cleanup via API
+  - Tag appropriately: `@critical` / `@ui` / `@smoke` / `@regression` / `@e2e`
+  - **Never Playwright** — Karate is the tool here.
+
+### Manual QA
+Steps the reviewer can run locally (`docker-compose.dev.yml` up, scenario
+to reproduce). Keep it short — if the manual list is long, automate more.
+
+### Performance / load
+Required when the design claims a latency / throughput / memory property,
+or touches the conversion hot path.
+-->
+
+## 10. Rollout & observability
+
+<!--
+How this change gets to production safely.
+
+### Release branch
+Which `release/X.Y.Z` is the target? Any coordination with a parallel
+release (e.g. R&D branch)?
+
+### Feature flag / staged rollout
+Does the change hide behind a flag surfaced via `/api/health`? If so, what
+flips the flag, and what is the default? HF Space deployments often need
+`deploymentMode === 'huggingface'` gating.
+
+### Observability
+  - Logs to add / extend (structured, low-cardinality keys)
+  - Metrics / counters (if added — call out any new Prometheus names)
+  - New error modes to watch for in `analysis_jobs.status = FAILED`
+
+### Rollback plan
+The revert that is safe to apply at any time:
+  - Which migration is reversible? Which is not?
+  - Which env var flip disables the feature without a redeploy?
+  - Any data cleanup needed after rollback?
+
+Link to the existing release / ops playbooks:
+  - Deployment: `docs/release/*` (also surfaced via `/release:deploy`)
+  - Rollback: also surfaced via `/release:rollback`
+  - Incident: `docs/operations/*` (also surfaced via `/ops:incident`)
+-->
+
+## 11. Open questions
+
+<!--
+Things the author explicitly does not know yet, phrased as questions the
+reviewer can answer or redirect. Empty is allowed once the design is
+Accepted — during Draft / In review, this section is where the honest
+uncertainty lives. Resolve or delete each entry before shipping.
+-->
+
+- ...
+- ...
+
+## 12. References
+
+<!--
+Links to everything a future reader would want.
+-->
+
+- **Issue:** https://github.com/scub-france/Docling-Studio/issues/195
+- **Related PRs / commits:**
+- **ADRs:** <ADR-NNN or "none planned">
+- **Project docs:**
+  - Architecture: `docs/architecture.md`
+  - Coding standards: `docs/architecture/coding-standards.md`
+  - ADR guide / template: `docs/architecture/adr-guide.md`, `docs/architecture/adr-template.md`
+  - Audit master: `docs/audit/master.md`
+  - E2E conventions: `e2e/CONVENTIONS.md`
+- **External:** <specs, upstream issues, dashboards, third-party docs>

docs/design/neo4j-integration.md

@@ -0,0 +1,435 @@
+# Neo4j integration — Docling-Studio v0.5.0
+
+Design doc for Neo4j integration targeting release 0.5.0.
+Target: Hackernoon hackathon demo (Neo4j partner).
+
+---
+
+## 1. Context and goals
+
+### Already in Docling-Studio
+- Ingestion pipeline: Docling parser → chunking (HybridChunker) → embedding → OpenSearch (vector index)
+- Vue 3 + FastAPI UI
+- Debug view to inspect/edit chunks before retrieval
+- Docker compose with existing services
+
+### What we add in v0.5.0
+- Neo4j as **graph-native storage** of the document structure
+- A new ingestion layer that stores the DoclingDocument tree faithfully as a graph
+- Minimal UI to visualize the graph (demo value to the judges)
+- Compose pipeline with Neo4j
+
+### Why graph-native (hackathon positioning)
+> Most document AI tools store parsed content as flat chunks in a vector DB.
+> Docling-Studio v0.5 introduces a graph-native storage layer on top of Neo4j,
+> preserving the full hierarchical structure of documents as first-class citizens.
+> This unlocks hybrid retrieval, agentic navigation, and structural debugging —
+> impossible with chunk-only stores.
+
+### Out of scope for v0.5.0 (roadmap mention only)
+- EnrichmentWriter (entities / summaries / keywords via docling-agent) — v0.6.0
+- Agent reasoning trace viewer — v0.6.0
+- RAG hybrid (graph traversal + vector) — v0.7.0
+- Document versioning — v0.7.0+
+
+---
+
+## 2. Architectural principles
+
+### Port & adapter, with nuance
+
+**Write side**: one `Writer` port, **composable stages** (not alternative adapters).
+Pipelines A and B are additive, not exclusive.
+
+```
+  CORE (always)          Pipeline A (RAG)       Pipeline B (agent-ready, v0.6+)
+  ┌─────────────┐        ┌────────────────┐    ┌───────────────────┐
+  │ TreeWriter  │ ─────▶ │ ChunkWriter    │    │ EnrichmentWriter  │
+  │             │        │ (existing      │    │ (via docling-     │
+  │             │        │  OpenSearch +  │    │  agent, v0.6+)    │
+  │             │        │  adds chunks   │    │                   │
+  │             │        │  to Neo4j)     │    │                   │
+  └─────────────┘        └────────────────┘    └───────────────────┘
+```
+
+```python
+# docling_studio/ingestion/pipeline.py
+class Writer(Protocol):
+    def write(self, doc: DoclingDocument, ctx: IngestionContext) -> None: ...
+
+# Explicit composition per use case
+def build_pipeline(config: PipelineConfig) -> list[Writer]:
+    writers = [TreeWriter(neo4j_driver)]
+    if config.rag_enabled:
+        writers.append(ChunkWriter(neo4j_driver, chunker, embedder, opensearch))
+    if config.enrichment_enabled:  # v0.6.0+
+        writers.append(EnrichmentWriter(neo4j_driver, docling_agent))
+    return writers
+```
+
+**Read side**: two distinct ports (same Neo4j backend, different queries).
+
+```python
+class RAGRetrievalPort(Protocol):
+    def search(self, query: str, k: int) -> list[Chunk]: ...
+    def similar(self, chunk_id: str, k: int) -> list[Chunk]: ...
+
+class TreeNavigationPort(Protocol):  # v0.6.0+
+    def get_outline(self, doc_id: str) -> Tree: ...
+    def read_node(self, ref: str) -> Element: ...
+    def list_children(self, ref: str) -> list[Element]: ...
+    def walk(self, ref: str, depth: int) -> SubTree: ...
+```
+
+---
+
+## 3. Neo4j schema
+
+### Constraints & indexes (created at boot)
+
+```cypher
+// Uniqueness
+CREATE CONSTRAINT document_id IF NOT EXISTS
+  FOR (d:Document) REQUIRE d.id IS UNIQUE;
+
+CREATE CONSTRAINT element_composite IF NOT EXISTS
+  FOR (e:Element) REQUIRE (e.doc_id, e.self_ref) IS UNIQUE;
+
+CREATE CONSTRAINT page_composite IF NOT EXISTS
+  FOR (p:Page) REQUIRE (p.doc_id, p.page_no) IS UNIQUE;
+
+CREATE CONSTRAINT chunk_id IF NOT EXISTS
+  FOR (c:Chunk) REQUIRE c.id IS UNIQUE;
+
+// Full-text index (element text search)
+CREATE FULLTEXT INDEX element_text IF NOT EXISTS
+  FOR (e:Element) ON EACH [e.text];
+
+// Simple indexes for per-doc queries
+CREATE INDEX element_doc IF NOT EXISTS FOR (e:Element) ON (e.doc_id);
+CREATE INDEX chunk_doc  IF NOT EXISTS FOR (c:Chunk)   ON (c.doc_id);
+```
+
+### Data model
+
+```cypher
+// Root document
+(:Document {
+  id: string,                    // UUID or PDF hash
+  title: string,
+  source_uri: string,            // path or S3
+  ingested_at: datetime,
+  docling_version: string,
+  stages_applied: list<string>,  // ["tree", "chunks"] etc.
+  last_tree_write: datetime,
+  last_chunk_write: datetime,
+  tenant_id: string              // simple multi-tenancy
+})
+
+// All tree elements (shared :Element label + specific label)
+(:Element:SectionHeader {doc_id, self_ref, text, level, prov_page, prov_bbox})
+(:Element:Paragraph    {doc_id, self_ref, text, prov_page, prov_bbox})
+(:Element:Table        {doc_id, self_ref, caption, cells_json, prov_page, prov_bbox})
+(:Element:Figure       {doc_id, self_ref, caption, image_uri, prov_page, prov_bbox})
+(:Element:ListItem     {doc_id, self_ref, text, marker, prov_page, prov_bbox})
+(:Element:Formula      {doc_id, self_ref, latex, text, prov_page, prov_bbox})
+
+// Page for layout provenance
+(:Page {doc_id, page_no, width, height})
+
+// Chunks (Pipeline A)
+(:Chunk {
+  id, doc_id,
+  text,
+  chunk_index,
+  embedding_ref,   // id in OpenSearch (no inline duplication)
+  token_count
+})
+```
+
+### Relations
+
+```cypher
+// Hierarchical structure
+(:Document)-[:HAS_ROOT]->(:Element)
+(:Element)-[:PARENT_OF {order: int}]->(:Element)  // order preserves sequence
+(:Element)-[:NEXT]->(:Element)                     // DFS pre-order reading
+
+// Layout
+(:Element)-[:ON_PAGE]->(:Page)
+
+// Pipeline A (chunking)
+(:Document)-[:HAS_CHUNK]->(:Chunk)
+(:Chunk)-[:DERIVED_FROM]->(:Element)  // back-reference; a chunk can span multiple elements
+```
+
+### Decisions
+
+| Decision | Choice | Rationale |
+|----------|-------|---------------|
+| Element composite key | `(doc_id, self_ref)` | self_ref not unique across docs |
+| Multi-tenancy | `tenant_id` property on Document | Simple, filterable, migrable to multi-db later |
+| Table cells | `cells_json` property | v0.5 KISS. May model `(Table)-[:HAS_CELL]->(Cell)` in v0.6+ |
+| Reading order | `[:NEXT]` chain + `{order}` on `PARENT_OF` | Both views useful |
+| Versioning | None (replace strategy on re-upload) | v0.5 KISS |
+| APOC | Not required | Pure Cypher is sufficient for v0.5 |
+
+### Re-ingestion strategy
+
+```cypher
+// Before ingesting, wipe existing
+MATCH (d:Document {id: $doc_id})
+OPTIONAL MATCH (d)-[:HAS_ROOT|HAS_CHUNK]->()
+DETACH DELETE d
+// Then re-walk cleanly
+```
+
+---
+
+## 4. Implementation plan (3 days)
+
+### Day 1 — Infra + schema
+
+- [ ] Add `neo4j` service to `docker-compose.yml` (`neo4j:5.15-community`, persistent volume, healthcheck)
+- [ ] Add env vars (`NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`) to `.env.example`
+- [ ] Create module `docling_studio/storage/neo4j/`:
+  - `driver.py` — neo4j-python driver wrapper (connection pool, context manager)
+  - `schema.py` — idempotent `bootstrap_schema()` (CREATE CONSTRAINT / INDEX at startup)
+  - `__init__.py` with exports
+- [ ] Hook `bootstrap_schema()` in FastAPI startup
+- [ ] Basic integration tests:
+  - Driver connection
+  - Schema bootstrap (idempotence verified)
+  - Simple round-trip: write Document, read Document, delete Document
+
+**Deliverable:** docker compose boots with healthy Neo4j, schema in place at init.
+
+### Day 2 — TreeWriter (write + read)
+
+- [ ] `storage/neo4j/tree_writer.py` — `DoclingDocument → Neo4j` walker
+  - `write_document(doc, tenant_id, driver)` in a transaction
+  - DFS pre-order, batched `MERGE` for perf
+  - Pages first, then Elements, then `PARENT_OF` / `NEXT` / `ON_PAGE` relations
+  - Dynamic labels based on `node.label` (`SectionHeader`, `Paragraph`, …)
+- [ ] `storage/neo4j/tree_reader.py` — inverse walker `Neo4j → DoclingDocument`
+  - `read_document(doc_id, driver) -> DoclingDocument`
+  - Loads all Elements + Pages, rebuilds the Pydantic structure
+  - Prerequisite for v0.6 (feeding docling-agent from Neo4j)
+- [ ] Integrate into existing ingestion pipeline:
+  - Add TreeWriter as first stage of `IngestionPipeline`
+  - `neo4j_enabled: bool` config toggle
+- [ ] Round-trip tests:
+  - 3–4 varied PDFs (academic, invoice, report)
+  - Assertion: `doc_original == read_document(write_document(doc_original))`
+  - Beware dates, bbox floats (tolerance)
+
+**Deliverable:** A PDF uploaded to Docling-Studio is fully present in Neo4j and rebuildable.
+
+### Day 3 — UI + ChunkWriter + packaging
+
+- [ ] `storage/neo4j/chunk_writer.py`:
+  - After existing chunking, push each Chunk to Neo4j
+  - Create `(:Chunk)-[:DERIVED_FROM]->(:Element)` via source element `self_ref`
+  - Do NOT duplicate embeddings (stay in OpenSearch, keep `embedding_ref`)
+- [ ] Frontend: new "Graph view" tab in debug panel
+  - Vue component with `cytoscape` (lighter, better layout API — see [ADR-001](../architecture/adrs/ADR-001-graph-visualization-library.md))
+  - FastAPI endpoint `/api/documents/{doc_id}/graph` returns full nodes + edges for the document, **capped at 200 pages** (HTTP 413 beyond; pagination deferred to v0.6). The endpoint must include a `truncated: bool` flag and `node_count` / `edge_count` in the response envelope so the UI can warn the user cleanly.
+  - View: vertical tree, colors per node type, click-to-zoom, hover details
+- [ ] Per-document "Graph-ready" / "RAG-ready" badge in list
+- [ ] README update:
+  - "Graph storage with Neo4j" section
+  - Schema diagram (Mermaid or image)
+  - 2–3 Cypher examples like "find all paragraphs under section X that mention Y"
+  - Neo4j badge in features list
+- [ ] (bonus if time) "Query explorer" dev tab for live demo: Cypher editor + results
+
+**Deliverable:** release 0.5.0 with Neo4j visible, functional, documented.
+
+---
+
+## 5. Proposed code structure
+
+```
+docling_studio/
+├── storage/
+│   ├── neo4j/
+│   │   ├── __init__.py
+│   │   ├── driver.py           # connection management
+│   │   ├── schema.py           # bootstrap_schema()
+│   │   ├── tree_writer.py      # DoclingDocument -> Neo4j
+│   │   ├── tree_reader.py      # Neo4j -> DoclingDocument
+│   │   ├── chunk_writer.py     # Chunks -> Neo4j
+│   │   └── queries.py          # shared Cypher queries
+│   ├── opensearch/             # (existing)
+│   └── ports.py                # Writer, RAGRetrievalPort protocols
+├── ingestion/
+│   └── pipeline.py             # IngestionPipeline composing Writers
+├── api/
+│   └── graph.py                # /api/documents/{id}/graph
+└── frontend/
+    └── components/
+        └── GraphView.vue       # cytoscape + graph API fetch
+```
+
+---
+
+## 6. Docker compose (added excerpt)
+
+```yaml
+services:
+  neo4j:
+    image: neo4j:5.15-community
+    environment:
+      NEO4J_AUTH: ${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-changeme}
+      NEO4J_PLUGINS: '["apoc"]'
+      NEO4J_server_memory_heap_initial__size: 512m
+      NEO4J_server_memory_heap_max__size: 1g
+    ports:
+      - "7474:7474"   # Browser UI (demo)
+      - "7687:7687"   # Bolt protocol
+    volumes:
+      - neo4j_data:/data
+      - neo4j_logs:/logs
+    healthcheck:
+      test: ["CMD-SHELL", "cypher-shell -u neo4j -p $${NEO4J_PASSWORD:-changeme} 'RETURN 1' || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  docling-studio-backend:
+    depends_on:
+      neo4j:
+        condition: service_healthy
+    environment:
+      NEO4J_URI: bolt://neo4j:7687
+      NEO4J_USER: neo4j
+      NEO4J_PASSWORD: ${NEO4J_PASSWORD:-changeme}
+
+volumes:
+  neo4j_data:
+  neo4j_logs:
+```
+
+---
+
+## 7. Tests
+
+### Unit tests
+- `tests/storage/neo4j/test_schema.py` — bootstrap is idempotent
+- `tests/storage/neo4j/test_tree_writer.py` — round-trip on synthetic DoclingDocument
+- `tests/storage/neo4j/test_chunk_writer.py` — chunks written with correct `DERIVED_FROM`
+
+### Integration tests
+- `tests/integration/test_ingestion_pipeline.py` — full pipeline on a real PDF
+- PDF fixtures: 1 academic (complex heading hierarchy), 1 invoice (tables), 1 report (lists)
+
+### E2E (bonus)
+- Upload PDF via UI → check structure in Neo4j Browser
+
+---
+
+## 8. Open decisions to settle before coding
+
+1. **Neo4j edition**: Community (free) or AuraDB (managed) ?
+   - Rec: Community in Docker for v0.5.0 dev/demo. AuraDB mentioned as prod option.
+
+2. **Chunks: duplicate embeddings in Neo4j or OpenSearch ref ?**
+   - Rec: OpenSearch ref (avoid duplication; OpenSearch remains source of truth for vectors). In v0.6+, consider native Neo4j vector index.
+
+3. **Graph view UI: cytoscape or vis-network ?**
+   - Decided: **Cytoscape.js** — see [ADR-001](../architecture/adrs/ADR-001-graph-visualization-library.md) for the full analysis.
+
+4. **Graph endpoint: return full doc or paginate ?**
+   - Decided: full doc for v0.5, **hard cap at 200 pages**. Beyond the cap, the endpoint returns HTTP 413 with a `truncated: true` flag; the UI shows "Graph too large to render — reduce scope". Pagination ships in v0.6.
+
+5. **Error strategy**: if Neo4j is down at ingestion, fail or degrade gracefully ?
+   - Rec: **fail fast** for v0.5 (avoid silent inconsistencies). `neo4j_required: bool` config option.
+
+---
+
+## 9. Hooks for later (v0.6.0+ — don't implement but prepare)
+
+**EnrichmentWriter (v0.6)** — will need:
+- The reader (Neo4j → DoclingDocument) to re-materialize the doc, feed docling-agent, re-patch enrichments
+- A stage addable to `IngestionPipeline` without touching other stages
+- An `:Entity` label (not created in v0.5 but schema-compatible)
+
+**Agent reasoning trace viewer (v0.6)** — will need:
+- An event stream (WebSocket) that v0.5 already prepares via the reactive UI
+- A node_ref ↔ Element correlation in Neo4j (our composite `self_ref` key is enough)
+
+**TreeNavigationPort (v0.7)** — will need:
+- Optimized Cypher queries for descendant/ancestor walk (indexes already provisioned)
+
+---
+
+## 10. v0.5.0 success criteria
+
+**Must have:**
+- [ ] A PDF uploaded to Docling-Studio is in Neo4j with structure preserved
+- [ ] Neo4j Browser shows the graph and is manually explorable
+- [ ] A graph visual in the Docling-Studio UI works
+- [ ] `docker compose up` works zero-config
+- [ ] README mentions Neo4j and describes the schema
+
+**Nice to have (decreasing priority):**
+- [ ] Graph-ready / RAG-ready badge per doc
+- [ ] Live query explorer in the UI
+- [ ] 2–3 example queries in README that do something impossible with vector-only
+
+**For the hackathon (post-release):**
+- [ ] 60s video: upload PDF → structure in Neo4j → cross-doc query impossible in vector-only
+- [ ] HackerNoon post explaining "graph-native documents" positioning
+- [ ] Explicit Neo4j partnership mention
+
+---
+
+## 11. Fundamental architectural decisions recap
+
+| Question | Answer |
+|----------|---------|
+| Is Neo4j source of truth or cache ? | **Source of truth** for structure. OpenSearch remains source of truth for embeddings. |
+| Does chunking go away ? | No, v0.5.0 keeps existing chunking. "Chunkless" is Pipeline B, v0.6+. |
+| Can it be toggled per doc ? | Yes — `stages_applied` on Document + pipeline config |
+| What about OpenSearch ? | Stays, stores vectors. Neo4j tracks `(:Chunk)-[:DERIVED_FROM]->(:Element)` links. |
+| Multi-tenancy ? | `tenant_id` property on Document, Cypher filter |
+| Versioning ? | None for v0.5.0 — replace strategy on re-upload |
+
+---
+
+## Appendix — Demo queries
+
+### Query 1 — All "Methods" sections across documents
+```cypher
+MATCH (d:Document)-[:HAS_ROOT]->(:Element)-[:PARENT_OF*]->(s:SectionHeader)
+WHERE toLower(s.text) CONTAINS 'method'
+RETURN d.title, s.text, s.level
+```
+
+### Query 2 — Context of a chunk (parent + siblings)
+```cypher
+MATCH (c:Chunk {id: $chunk_id})-[:DERIVED_FROM]->(e:Element)
+MATCH (e)<-[:PARENT_OF]-(parent:Element)
+MATCH (parent)-[:PARENT_OF]->(sibling:Element)
+RETURN parent, collect(sibling) AS siblings
+```
+
+### Query 3 — All tables from a document type
+```cypher
+MATCH (d:Document)-[:HAS_ROOT]->(:Element)-[:PARENT_OF*]->(t:Table)
+WHERE d.source_uri CONTAINS 'invoices/'
+RETURN d.title, t.caption, t.cells_json
+```
+
+### Query 4 — Direct children of a section (ordered)
+```cypher
+MATCH (s:Element {doc_id: $doc_id, self_ref: $section_ref})
+MATCH (s)-[pof:PARENT_OF]->(child)
+RETURN child
+ORDER BY pof.order
+```
+
+---
+
+*Single reference doc for Neo4j v0.5.0 implementation.
+Read this first in the implementation thread.*

docs/design/reasoning-trace.md

@@ -0,0 +1,253 @@
+# Reasoning Trace Viewer — Docling-Studio v0.6.0 (R&D preview)
+
+Design doc for the `docling-agent` reasoning trace viewer.
+Targeted release: **v0.6.0** (R&D branched from `release/0.5.0` in parallel to the
+0.5 build, so the Neo4j foundation can be leveraged without blocking the hackathon deliverable).
+
+Positioning one-liner:
+> Studio becomes the **reference viewer for any `docling-agent` run** — not another
+> chatbot. The PDF is the debug surface.
+
+---
+
+## 1. Context
+
+### Upstream trigger
+Peter Staar (IBM) suggested surfacing the LLM reasoning trace as `docling-agent`
+walks a `DoclingDocument` outline (chunkless RAG, new IBM repo).
+
+### `docling-agent` in one paragraph
+`DoclingRAGAgent(model_id, tools, max_iterations=5).run(task, sources=[doc])` returns
+a `RAGResult` with `answer`, `converged`, and `iterations: list[RAGIteration]`.
+Each `RAGIteration` carries: `iteration`, `section_ref` (JSON-pointer, e.g. `#/texts/3`),
+`reason`, `can_answer`, `response`, `section_text_length`. No bbox — must be resolved
+through `DoclingDocument.<items>[i].prov[0].bbox` + `page_no`. Runs on Mellea
+(Ollama / OpenAI / HF / WatsonX / LiteLLM / Bedrock). Observability is stdout logs only.
+
+### What Studio already brings
+- **Neo4j graph of the document** (0.5.0, just landed) — every `Element` is keyed by
+  `(doc_id, self_ref)`, Cytoscape node id is `elem::${self_ref}`. **This is the
+  killer enabler.** `RAGIteration.section_ref → node` is a string concat, no resolver.
+- `GraphView.vue` (Cytoscape + dagre) already handles styles via selectors
+  (`selector: 'edge[type = "NEXT"]'`, `selector: 'node[kind = "section"]'`) — adding
+  a `visited` class + `REASONING_NEXT` synthetic edge type is ~20 LOC of style.
+- `analysis_jobs.document_json` in SQLite → DoclingDocument available for the sidecar
+  runner (no PDF re-conversion). Not used by the viewer itself.
+
+### Personas
+- **v1 (this plan)**: dev / integrator of `docling-agent` debugging a run that went wrong.
+- **v2 (roadmap)**: live runner with synchronized demo UX.
+- v3+ (non-goals here): business analyst for semantic navigation, batch QA.
+
+---
+
+## 2. Scope split — **debug first, demo second**
+
+Rendering surface pivoted: **the trace is drawn on the Neo4j graph**, not on the PDF.
+See §1. This kills the whole bbox-resolution stack from v1.
+
+| Phase | Value | Runtime deps | Surface |
+|---|---|---|---|
+| **v1 — Debug (this plan)** | Import externally-produced `RAGResult` JSON, overlay trace on the existing GraphView | **None** server-side. Pure frontend. | GraphView: visited nodes highlighted in order, synthetic `REASONING_NEXT` edges |
+| **v2 — Demo (follow-up)** | Run the agent live against a loaded document | Ollama + Mellea + `docling-agent` (new opt-dep group `rag`) | Same GraphView + SSE streaming of iterations, staggered reveal |
+
+Building v1 first de-risks the **graph-trace UX** on real runs (produced by the
+R&D sidecar — see `experiments/reasoning-trace/`) before wiring the live runner.
+Code shared between v1 and v2 is the GraphView overlay itself — 100 % reused.
+
+**Prerequisite for v1**: the target document must have been processed through the
+"Maintain" step (Neo4j pipeline). Otherwise the graph is empty and the trace has
+nowhere to render — surface an explicit "Run the Maintain step first" empty state.
+
+---
+
+## 3. v1 — Debug mode (frontend-only)
+
+### 3.1 No backend changes in v1
+
+The GraphView already loads nodes keyed by `self_ref` via `GET /api/documents/{doc_id}/graph`.
+Iteration `section_ref` → Cytoscape node id is `` `elem::${section_ref}` `` — a client-side
+string concat. Nothing to compute server-side.
+
+Consequences:
+- No new router, no new service, no new pydantic model, no new migration.
+- No dependency on `docling-agent` in `document-parser/requirements.txt`.
+- `RAGResult` JSON (as produced by `experiments/reasoning-trace/`) is consumed
+  entirely by the frontend.
+
+### 3.2 Frontend — feature folder
+
+New `frontend/src/features/reasoning/`:
+
+```
+reasoning/
+├── store/reasoningStore.ts         # Pinia: trace, activeIteration, importDialogOpen
+├── ui/
+│   ├── ReasoningPanel.vue          # Side panel: query, answer, iteration list
+│   ├── IterationCard.vue           # Single iteration row (reason + can_answer badge)
+│   ├── ImportTraceDialog.vue       # Drag-drop / paste RAGResult JSON
+│   └── GraphReasoningOverlay.ts    # NOT a component — a plugin that decorates cy
+└── types.ts                        # RAGIteration, RAGResult mirror types
+```
+
+### 3.3 Graph overlay — how it's drawn
+
+`GraphReasoningOverlay` takes the existing `cy` Cytoscape instance (exposed from
+`GraphView.vue` via `defineExpose`) and:
+
+1. For each `iteration[i].section_ref`, find node `` `elem::${section_ref}` ``. If
+   missing, tag as `resolution_status: "not_in_graph"` and show a warning in the panel
+   (common cause: doc not processed through Maintain, or agent returned a ref that
+   points at a non-Element node).
+2. Add class `visited` + data attribute `visitOrder: i+1` on matched nodes.
+3. Insert **synthetic edges** between successive visited nodes with `type: "REASONING_NEXT"`
+   and `data: { order: i }`. These edges are UI-only, never written to Neo4j.
+4. On import, fit viewport to the visited subgraph (`cy.fit(cy.$('.visited'), 80)`).
+5. On iteration card click → `cy.$(`#elem::${ref}`).flashClass('pulse', 800)` +
+   centered pan.
+
+Cytoscape styles (append to the existing stylesheet array in `GraphView.vue`):
+
+```js
+{ selector: 'node.visited',
+  style: { 'border-color': '#EA580C', 'border-width': 3, 'overlay-opacity': 0 } },
+{ selector: 'node.visited[visitOrder]',
+  style: { label: 'data(visitOrder)', 'text-valign': 'top',
+           'text-background-color': '#EA580C', 'text-background-opacity': 1,
+           'color': '#FFFFFF', 'font-weight': 700 } },
+{ selector: 'edge[type = "REASONING_NEXT"]',
+  style: { 'line-color': '#EA580C', 'target-arrow-color': '#EA580C',
+           'target-arrow-shape': 'triangle', 'curve-style': 'bezier',
+           width: 2, 'z-index': 99 } },
+```
+
+Color ramp: single warm color (`#EA580C`) for v1. Gradient cold→warm is v2 polish.
+
+### 3.4 Integration points
+
+- `StudioPage.vue` → "Maintain" tab gains an **"Import reasoning trace"** action
+  (don't add a 3rd mode — the viz lives inside the graph view, not a new workspace).
+- `GraphView.vue` → add `defineExpose({ cy })` + a `<slot name="overlay" :cy="cy"/>`
+  that the parent can populate with `<ReasoningPanel>`.
+- `ReasoningPanel` appears as a right rail when a trace is loaded; collapsible.
+
+### 3.5 Empty / error states
+
+- **Graph empty for this doc** → "Run the Maintain step first. Neo4j has no graph for
+  this document yet." (the Maintain button is literally next to it.)
+- **All `section_ref`s unresolved in graph** → "None of the visited sections exist in
+  the graph. The agent may have been run against a different document, or the doc was
+  re-analyzed since. Re-run Maintain or re-run the agent."
+- **Some resolved, some not** → show trace with the missing ones greyed out in the panel.
+
+### 3.6 Tests
+
+No backend tests in v1 (no backend code).
+
+Frontend (Vitest):
+- `reasoningStore.test.ts` — import trace, active iteration transitions, reset on doc change.
+- `graphReasoningOverlay.test.ts` — given a mock `cy` (`cytoscape({ headless: true })`)
+  with a known node set, verify `visited` class applied to the right ids and the
+  correct synthetic edges added.
+- `ReasoningPanel.test.ts` — empty / loaded / partial-resolution states.
+
+### 3.7 Out of scope for v1
+- Live agent runner (v2).
+- Multi-doc queries — reject import if `RAGResult` was produced against `len(sources) > 1`.
+- Phrase-level attribution — `docling-agent` doesn't emit it.
+- Persisting traces in Neo4j — see §7.
+- PDF highlighting — dropped from v1. Could come back as v2.5 if demand exists.
+
+---
+
+## 4. File inventory (v1)
+
+**New — R&D sidecar** (already scaffolded on this branch)
+- `experiments/reasoning-trace/inspect_doc.py` — self-contained `uv run` script.
+- `experiments/reasoning-trace/README.md`
+- `experiments/reasoning-trace/.gitignore`
+
+**New — frontend**
+- `frontend/src/features/reasoning/**` (see §3.2)
+- Vitest siblings under `**/*.test.ts`
+
+**Touched**
+- `frontend/src/features/analysis/ui/GraphView.vue` — `defineExpose({ cy })` +
+  `<slot name="overlay">` + 3 new style selectors.
+- `frontend/src/pages/StudioPage.vue` — "Import reasoning trace" action in the
+  Maintain tab rail.
+
+**Untouched**
+- Entire `document-parser/` backend — no new router, service, schema, or dep.
+- `pyproject.toml` / `requirements.txt` — **no new runtime dep in v1**.
+- Neo4j schema — synthetic edges are client-side Cytoscape only.
+- OpenSearch / ingestion — untouched.
+- SQLite schema — no migration.
+
+---
+
+## 5. Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| `RAGResult` schema drifts in `docling-agent` | `schema_version` discriminator; strict pydantic; one canonical fixture from Peter pinned in CI. |
+| `section_ref` variants (`#/texts/3` vs `#/body/texts/3`) | Normalize in parser; regex test matrix. |
+| Synthetic groups without `prov` | Documented child-walk fallback + `resolved_via_child` status surfaced in UI. |
+| Large `RAGResult` (hundreds of iterations) | Hard-cap `iterations` at 50 in v1 (Peter's agent uses `max_iterations=5` by default) — return 413 above. |
+| `document_json` blob large (some docs > 5 MB) | `analysis_repo` already handles it; but **do not** log the blob. Add redaction test. |
+| Section ref not in graph (doc not through Maintain, or re-analyzed) | Explicit empty-state in `ReasoningPanel` with a link to the Maintain tab. Partial resolution shown as grey in the trace list. |
+| Feature creeping into 0.5.0 | This branch targets **v0.6.0**. Do not merge into `release/0.5.0`. Rebase onto the next release branch when cut. |
+
+---
+
+## 6. Spec anchoring
+
+Pin the `RAGResult` shape to **docling-agent commit SHA at the time of v1 merge** in
+a short ADR `docs/architecture/adrs/ADR-002-rag-result-schema.md`. The schema is
+upstream, unversioned, and will move — this doc freezes the contract Studio imports.
+
+---
+
+## 7. v2 preview — demo mode (not in this plan)
+
+Kept here to constrain v1 interfaces so nothing needs rewriting:
+- `POST /api/rag/answer` — server-side runner. Accepts `{doc_id, question, model_id}`.
+  Streams iterations via SSE. Frontend consumes the stream with the same
+  `GraphReasoningOverlay` used by v1 import — iterations appear one by one with
+  staggered reveal (~400 ms) as the SSE stream drips them in.
+- Ollama wired through `Mellea` — new optional dep group `rag`.
+- Persist traces in Neo4j as `(:ReasoningRun {id, query, converged})-[:VISITED {order,
+  reason, can_answer}]->(:Element)` for replay + cross-run analytics. Leverages
+  `TreeWriter` pattern already present. This is where the synthetic UI edges become
+  real graph edges.
+- Cross-run comparison view: overlay multiple runs on the same graph, diff the paths.
+
+---
+
+## 8. Branch & workflow
+
+- Branch: **`feature/reasoning-trace`** off `origin/release/0.5.0`.
+- Merge target: **next release branch (`release/0.6.0`)** once cut — *not* `0.5.0`.
+- Until then: live on the feature branch; rebase onto `release/0.5.0` periodically to
+  absorb Neo4j fixes.
+- Issues: one umbrella + one per §4 subsystem (resolver, endpoint, UI panel, overlay,
+  import dialog, tests). Commit with `Closes #NNN` per project convention.
+- PR: opened against `release/0.6.0` when available; draft in the meantime.
+
+---
+
+## 9. Open questions (answered by the sidecar first run)
+
+1. Are emitted `section_ref`s reachable as `elem::${ref}` in the Neo4j graph built
+   by `TreeWriter`? I.e. is the `self_ref` the agent sees the same `self_ref` we
+   wrote to the graph? (Expected yes — both come from the same `DoclingDocument` —
+   but the sidecar on a real doc from SQLite will confirm in one run.)
+2. Hit rate of the agent: with `max_iterations=5` and `granite4:micro-h`, does it
+   converge, and how many sections does it actually visit? Determines if the overlay
+   ever has more than 1–2 marked nodes (and whether `REASONING_NEXT` edges are worth
+   the effort vs just node markers).
+3. Quality of `iteration.reason` — is it substantive enough to show in the panel, or
+   LLM filler we should hide? Sidecar output will tell.
+4. Fallback when no section headers exist (`RAGResult(iterations=[], converged=True,
+   answer=<full md>)` — see rag.py): what does the panel show? Probably a degraded
+   "no trace available, full-doc answer" state.

docs/getting-started.md

@@ -1,15 +1,28 @@
 # Getting Started
 
-Docling Studio ships two Docker image variants:
+## Quick Start
 
-| Variant | Image tag | Size | Description |
+One command, nothing else to install:
-|---------|-----------|------|-------------|
+
-| **remote** | `latest-remote` | ~270 MB | Lightweight — delegates to an external [Docling Serve](https://github.com/DS4SD/docling-serve) instance |
+```bash
-| **local** | `latest-local` | ~1.9 GB | Full — runs Docling in-process, CPU-only (downloads ML models on first run) |
+docker run -p 3000:3000 ghcr.io/scub-france/docling-studio:latest-local
+```
+
+Open [http://localhost:3000](http://localhost:3000), upload a PDF, and get results. That's it.
+
+!!! note
+    The first analysis takes longer as Docling downloads its ML models (~400 MB). Subsequent runs are fast.
 
 ![Docker architecture](images/docker.png){ width="600" }
 
-## Docker — remote mode (fastest)
+## Image Variants
+
+| Variant | Image tag | Size | Description |
+|---------|-----------|------|-------------|
+| **local** | `latest-local` | ~1.9 GB | Full — runs Docling in-process, CPU-only |
+| **remote** | `latest-remote` | ~270 MB | Lightweight — delegates to an external [Docling Serve](https://github.com/DS4SD/docling-serve) instance |
+
+For remote mode:
 
 ```bash
 docker run -p 3000:3000 \
@@ -17,27 +30,19 @@ docker run -p 3000:3000 \
   ghcr.io/scub-france/docling-studio:latest-remote
 ```
 
-## Docker — local mode (self-contained)
+## Docker Compose
-
-```bash
-docker run -p 3000:3000 ghcr.io/scub-france/docling-studio:latest-local
-```
-
-> **Note:** The first analysis takes longer as Docling downloads its ML models (~400 MB). Subsequent runs are fast.
-
-Open [http://localhost:3000](http://localhost:3000).
-
-## Docker Compose (recommended for development)
 
 ```bash
 git clone https://github.com/scub-france/Docling-Studio.git
 cd Docling-Studio
 
-# Local mode (default)
+# Simple mode (backend + frontend only)
 docker compose up --build
 
-# Remote mode
+# With ingestion pipeline (OpenSearch + embeddings)
-CONVERSION_MODE=remote DOCLING_SERVE_URL=http://your-docling-serve:5001 docker compose up --build
+docker compose --profile ingestion \
+  -f docker-compose.yml -f docker-compose.ingestion.yml \
+  up --build
 ```
 
 ## Local Development
@@ -136,10 +141,48 @@ All configuration is done via environment variables:
 | `UPLOAD_DIR` | `./uploads` | File storage directory |
 | `DB_PATH` | `./data/docling_studio.db` | SQLite database path |
 | `CONVERSION_TIMEOUT` | `600` | Max seconds per Docling conversion |
+| `BATCH_PAGE_SIZE` | `10` | Pages per batch (`0` = process all at once) |
 | `MAX_CONCURRENT_ANALYSES` | `3` | Maximum parallel analysis jobs |
 | `DEPLOYMENT_MODE` | `self-hosted` | `self-hosted` or `huggingface` (shows disclaimer banner) |
+| `MAX_FILE_SIZE_MB` | `50` | Maximum upload file size in MB (`0` = unlimited) |
+| `MAX_PAGE_COUNT` | `0` | Maximum number of pages per document (`0` = unlimited) |
+| `RATE_LIMIT_RPM` | `100` | Max requests per minute per IP (`0` = disabled) |
 | `APP_VERSION` | `dev` | Application version (set automatically by CI/Docker) |
 
+## Upload Limits
+
+Docling Studio enforces configurable limits on uploaded documents to protect the server against oversized files and long-running analyses:
+
+- **`MAX_FILE_SIZE_MB`** (default `50`) — rejects uploads exceeding this size. Validated at two levels: early `Content-Length` check and streaming byte count.
+- **`MAX_PAGE_COUNT`** (default `0` = unlimited) — rejects documents with more pages than allowed. Useful on shared instances or Hugging Face Spaces to cap processing time.
+
+Both limits are exposed in the `/api/health` endpoint so the frontend can display them to the user before upload. Set either to `0` to disable the corresponding check.
+
+## Ingestion Pipeline (opt-in)
+
+Docling Studio can optionally index extracted chunks into [OpenSearch](https://opensearch.org/) for vector and full-text search. This requires two additional services (OpenSearch + embedding) and is **disabled by default**.
+
+To enable ingestion with Docker Compose:
+
+```bash
+docker compose --profile ingestion \
+  -f docker-compose.yml -f docker-compose.ingestion.yml \
+  up --build
+```
+
+When ingestion is enabled, the UI shows:
+
+- An **Ingest** button in Studio to push chunks to OpenSearch
+- An **OpenSearch** connection status badge in the sidebar
+- **Indexed / Not indexed** filters on the Documents page
+- A **Search** page for full-text and vector search across indexed documents
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENSEARCH_URL` | — | OpenSearch endpoint (empty = ingestion disabled) |
+| `EMBEDDING_URL` | — | Embedding service endpoint (empty = ingestion disabled) |
+| `EMBEDDING_DIMENSION` | `384` | Vector dimension (must match embedding model) |
+
 ## System Requirements
 
 | | Remote image | Local image |

docs/index.md

@@ -18,7 +18,8 @@ Upload a PDF, configure the extraction pipeline, and visualize the results — t
 - **Document management** — upload, list, delete
 - **Analysis history** — re-visit and open past analyses
 - **Feature flags** — capabilities adapt to the conversion engine (local vs remote)
-- **Rate limiting** — 60 requests per minute per IP to protect the backend
+- **Upload limits** — configurable max file size (`MAX_FILE_SIZE_MB`) and max page count (`MAX_PAGE_COUNT`) per document
+- **Rate limiting** — configurable requests per minute per IP (`RATE_LIMIT_RPM`)
 - **Deployment modes** — self-hosted (default) or HuggingFace Spaces (with disclaimer banner)
 - **Health endpoint** — `/api/health` reports engine type, deployment mode, and database status
 - **Dark / Light theme** and **FR / EN** localization

document-parser/api/analyses.py

@@ -13,6 +13,7 @@ from api.schemas import (
     ChunkResponse,
     CreateAnalysisRequest,
     RechunkRequest,
+    UpdateChunkTextRequest,
 )
 from services.analysis_service import AnalysisService
 
@@ -80,22 +81,22 @@ async def list_analyses(service: ServiceDep) -> list[AnalysisResponse]:
     return [_to_response(j) for j in jobs]
 
 
-@router.get("/{job_id}", response_model=AnalysisResponse)
+@router.get("/{analysis_id}", response_model=AnalysisResponse)
-async def get_analysis(job_id: str, service: ServiceDep) -> AnalysisResponse:
+async def get_analysis(analysis_id: str, service: ServiceDep) -> AnalysisResponse:
     """Get a single analysis job."""
-    job = await service.find_by_id(job_id)
+    job = await service.find_by_id(analysis_id)
     if not job:
         raise HTTPException(status_code=404, detail="Analysis not found")
     return _to_response(job)
 
 
-@router.post("/{job_id}/rechunk", response_model=list[ChunkResponse])
+@router.post("/{analysis_id}/rechunk", response_model=list[ChunkResponse])
 async def rechunk_analysis(
-    job_id: str, body: RechunkRequest, service: ServiceDep
+    analysis_id: str, body: RechunkRequest, service: ServiceDep
 ) -> list[ChunkResponse]:
     """Re-chunk a completed analysis with new chunking options."""
     try:
-        chunks = await service.rechunk(job_id, body.chunkingOptions.model_dump())
+        chunks = await service.rechunk(analysis_id, body.chunkingOptions.model_dump())
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e)) from e
     return [
@@ -110,9 +111,55 @@ async def rechunk_analysis(
     ]
 
 
-@router.delete("/{job_id}", status_code=204)
+@router.patch("/{analysis_id}/chunks/{chunk_index}", response_model=list[ChunkResponse])
-async def delete_analysis(job_id: str, service: ServiceDep) -> None:
+async def update_chunk_text(
+    analysis_id: str, chunk_index: int, body: UpdateChunkTextRequest, service: ServiceDep
+) -> list[ChunkResponse]:
+    """Update the text of a single chunk by index."""
+    try:
+        chunks = await service.update_chunk_text(analysis_id, chunk_index, body.text)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    return [
+        ChunkResponse(
+            text=c["text"],
+            headings=c.get("headings", []),
+            source_page=c.get("sourcePage"),
+            token_count=c.get("tokenCount", 0),
+            bboxes=[ChunkBboxResponse(page=b["page"], bbox=b["bbox"]) for b in c.get("bboxes", [])],
+            modified=c.get("modified", False),
+            deleted=c.get("deleted", False),
+        )
+        for c in chunks
+    ]
+
+
+@router.delete("/{analysis_id}/chunks/{chunk_index}", response_model=list[ChunkResponse])
+async def delete_chunk(
+    analysis_id: str, chunk_index: int, service: ServiceDep
+) -> list[ChunkResponse]:
+    """Soft-delete a chunk by index (marks it as deleted)."""
+    try:
+        chunks = await service.delete_chunk(analysis_id, chunk_index)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    return [
+        ChunkResponse(
+            text=c["text"],
+            headings=c.get("headings", []),
+            source_page=c.get("sourcePage"),
+            token_count=c.get("tokenCount", 0),
+            bboxes=[ChunkBboxResponse(page=b["page"], bbox=b["bbox"]) for b in c.get("bboxes", [])],
+            modified=c.get("modified", False),
+            deleted=c.get("deleted", False),
+        )
+        for c in chunks
+    ]
+
+
+@router.delete("/{analysis_id}", status_code=204, response_model=None)
+async def delete_analysis(analysis_id: str, service: ServiceDep) -> None:
     """Delete an analysis job."""
-    deleted = await service.delete(job_id)
+    deleted = await service.delete(analysis_id)
     if not deleted:
         raise HTTPException(status_code=404, detail="Analysis not found")

document-parser/api/documents.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
+from pathlib import Path
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request, UploadFile
@@ -85,7 +87,7 @@ async def get_document(doc_id: str, service: ServiceDep) -> DocumentResponse:
     return _to_response(doc)
 
 
-@router.delete("/{doc_id}", status_code=204)
+@router.delete("/{doc_id}", status_code=204, response_model=None)
 async def delete_document(doc_id: str, service: ServiceDep) -> None:
     """Delete a document and its file."""
     deleted = await service.delete(doc_id)
@@ -112,9 +114,12 @@ async def preview(
         )
 
     try:
-        with open(doc.storage_path, "rb") as f:
+        # File read + PDF rasterisation are both blocking; offload to a
-            file_content = f.read()
+        # worker thread so the event loop stays free for other requests.
-        png_bytes = DocumentService.generate_preview(file_content, page=page, dpi=dpi)
+        file_content = await asyncio.to_thread(Path(doc.storage_path).read_bytes)
+        png_bytes = await asyncio.to_thread(
+            DocumentService.generate_preview, file_content, page=page, dpi=dpi
+        )
         return Response(content=png_bytes, media_type="image/png")
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e)) from e

document-parser/api/graph.py

@@ -0,0 +1,123 @@
+"""Graph API — returns a cytoscape-shaped view of the document structure.
+
+Two endpoints:
+- `/graph` — read from Neo4j. Rich graph (elements + chunks + pages + merges).
+  Requires the Maintain step (IngestionPipeline) to have run for the document.
+- `/reasoning-graph` — built on-the-fly from the SQLite `document_json` blob.
+  No Neo4j dependency. Lighter graph (no chunks) but enough to render the
+  reasoning-trace overlay on top of `GraphView`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+from infra.docling_graph import build_graph_payload
+from infra.neo4j import fetch_graph
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/documents", tags=["graph"])
+
+MAX_PAGES = 200
+
+
+class GraphNode(BaseModel):
+    id: str
+    group: str
+    label: str | None = None
+
+    model_config = {"extra": "allow"}
+
+
+class GraphEdge(BaseModel):
+    id: str
+    source: str
+    target: str
+    type: str
+    order: int | None = None
+
+
+class GraphResponse(BaseModel):
+    doc_id: str
+    nodes: list[GraphNode]
+    edges: list[GraphEdge]
+    node_count: int
+    edge_count: int
+    truncated: bool
+    page_count: int
+
+
+@router.get("/{doc_id}/graph", response_model=GraphResponse)
+async def get_document_graph(doc_id: str, request: Request) -> GraphResponse:
+    neo = getattr(request.app.state, "neo4j", None)
+    if neo is None:
+        raise HTTPException(status_code=503, detail="Neo4j is not configured")
+
+    payload = await fetch_graph(neo, doc_id, max_pages=MAX_PAGES)
+    if payload is None:
+        raise HTTPException(status_code=404, detail=f"No graph for document {doc_id}")
+    if payload.truncated:
+        raise HTTPException(
+            status_code=413,
+            detail=(
+                f"Graph too large: document has {payload.page_count} pages "
+                f"(cap {MAX_PAGES}). Pagination ships in v0.6."
+            ),
+        )
+
+    return GraphResponse(
+        doc_id=payload.doc_id,
+        nodes=[GraphNode(**n) for n in payload.nodes],
+        edges=[GraphEdge(**e) for e in payload.edges],
+        node_count=payload.node_count,
+        edge_count=payload.edge_count,
+        truncated=payload.truncated,
+        page_count=payload.page_count,
+    )
+
+
+@router.get("/{doc_id}/reasoning-graph", response_model=GraphResponse)
+async def get_reasoning_graph(doc_id: str, request: Request) -> GraphResponse:
+    """Graph projection built from SQLite `document_json` — no Neo4j needed.
+
+    Serves the reasoning-trace viewer, which only needs the element/page/edge
+    structure to overlay iterations onto.
+    """
+    analysis_repo = getattr(request.app.state, "analysis_repo", None)
+    if analysis_repo is None:
+        raise HTTPException(status_code=500, detail="AnalysisRepository not wired")
+
+    latest = await analysis_repo.find_latest_completed_by_document(doc_id)
+    if latest is None or not latest.document_json:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No completed analysis with document_json for {doc_id}",
+        )
+
+    payload = build_graph_payload(
+        latest.document_json,
+        doc_id=doc_id,
+        title=latest.document_filename or doc_id,
+        max_pages=MAX_PAGES,
+    )
+    if payload.truncated:
+        raise HTTPException(
+            status_code=413,
+            detail=(
+                f"Graph too large: document has {payload.page_count} pages "
+                f"(cap {MAX_PAGES}). Pagination ships in v0.6."
+            ),
+        )
+
+    return GraphResponse(
+        doc_id=payload.doc_id,
+        nodes=[GraphNode(**n) for n in payload.nodes],
+        edges=[GraphEdge(**e) for e in payload.edges],
+        node_count=payload.node_count,
+        edge_count=payload.edge_count,
+        truncated=payload.truncated,
+        page_count=payload.page_count,
+    )

document-parser/api/ingestion.py

@@ -0,0 +1,119 @@
+"""Ingestion API router — trigger and manage vector ingestion pipeline."""
+
+from __future__ import annotations
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+
+from api.schemas import (
+    IngestionResponse,
+    IngestionStatusResponse,
+    SearchResponse,
+    SearchResultItem,
+)
+from services.analysis_service import AnalysisService
+from services.ingestion_service import IngestionService
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/ingestion", tags=["ingestion"])
+
+
+def _get_ingestion_service(request: Request) -> IngestionService:
+    svc = request.app.state.ingestion_service
+    if svc is None:
+        raise HTTPException(
+            status_code=503,
+            detail="Ingestion not available (EMBEDDING_URL and OPENSEARCH_URL required)",
+        )
+    return svc
+
+
+def _get_analysis_service(request: Request) -> AnalysisService:
+    return request.app.state.analysis_service
+
+
+IngestionDep = Annotated[IngestionService, Depends(_get_ingestion_service)]
+AnalysisDep = Annotated[AnalysisService, Depends(_get_analysis_service)]
+
+
+@router.post("/{analysis_id}", response_model=IngestionResponse)
+async def ingest_analysis(
+    analysis_id: str,
+    ingestion: IngestionDep,
+    analysis: AnalysisDep,
+) -> IngestionResponse:
+    """Ingest a completed analysis into the vector index.
+
+    Takes the chunks from an existing analysis, embeds them,
+    and indexes them into OpenSearch.
+    """
+    job = await analysis.find_by_id(analysis_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Analysis not found")
+    if job.status.value != "COMPLETED":
+        raise HTTPException(status_code=400, detail="Analysis is not completed")
+    if not job.chunks_json:
+        raise HTTPException(status_code=400, detail="Analysis has no chunks — run chunking first")
+
+    try:
+        result = await ingestion.ingest(
+            doc_id=job.document_id,
+            filename=job.document_filename or "unknown",
+            chunks_json=job.chunks_json,
+        )
+    except Exception as e:
+        logger.exception("Ingestion failed for analysis %s", analysis_id)
+        raise HTTPException(status_code=500, detail=f"Ingestion failed: {e}") from e
+
+    return IngestionResponse(
+        doc_id=result.doc_id,
+        chunks_indexed=result.chunks_indexed,
+        embedding_dimension=result.embedding_dimension,
+    )
+
+
+@router.delete("/{doc_id}", status_code=204, response_model=None)
+async def delete_ingested_document(doc_id: str, ingestion: IngestionDep) -> None:
+    """Delete all indexed chunks for a document."""
+    await ingestion.delete_document(doc_id)
+
+
+@router.get("/status", response_model=IngestionStatusResponse)
+async def ingestion_status(request: Request) -> IngestionStatusResponse:
+    """Check if the ingestion pipeline is available and OpenSearch is connected."""
+    svc = request.app.state.ingestion_service
+    if svc is None:
+        return IngestionStatusResponse(available=False, opensearch_connected=False)
+
+    connected = await svc.ping()
+    return IngestionStatusResponse(available=True, opensearch_connected=connected)
+
+
+@router.get("/search", response_model=SearchResponse)
+async def search_chunks(
+    ingestion: IngestionDep,
+    q: str = Query(..., min_length=1, description="Search query"),
+    doc_id: str | None = Query(None, description="Filter by document ID"),
+    k: int = Query(20, ge=1, le=100, description="Max results"),
+) -> SearchResponse:
+    """Full-text search across indexed chunks.
+
+    Returns matching chunks with content and metadata.
+    Optionally filter by document ID.
+    """
+    results = await ingestion.search_fulltext(q, k=k, doc_id=doc_id)
+    items = [
+        SearchResultItem(
+            doc_id=r.chunk.doc_id,
+            filename=r.chunk.filename,
+            content=r.chunk.content,
+            chunk_index=r.chunk.chunk_index,
+            page_number=r.chunk.page_number,
+            score=r.score,
+            headings=r.chunk.headings,
+        )
+        for r in results
+    ]
+    return SearchResponse(results=items, total=len(items), query=q)

document-parser/api/reasoning.py

@@ -0,0 +1,113 @@
+"""Reasoning API — HTTP layer over a `ReasoningRunner` port.
+
+`POST /api/documents/:id/reasoning` invokes the wired-up `ReasoningRunner`
+against the stored `DoclingDocument` and returns a `ReasoningResultResponse`
+in the same shape the v1 import dialog already consumes — so the frontend
+overlay code is fully reused.
+
+This module has zero coupling to docling-agent / mellea / docling-core. The
+runner (concrete adapter in `infra/docling_agent_reasoning.py`) is set on
+`app.state.reasoning_runner` at boot when `REASONING_ENABLED=true` and the
+deps are importable. Otherwise it stays `None` and we 503.
+
+Sync blocking call offloaded to a thread by the adapter so we don't stall
+the event loop. No streaming at this step (see design doc §7 for v2 SSE plan).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+from domain.ports import ReasoningParseError, ReasoningRunner
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/documents", tags=["reasoning"])
+
+
+class ReasoningRunRequest(BaseModel):
+    query: str
+    # Optional per-run override; falls back to the runner's default model.
+    model_id: str | None = None
+
+
+class ReasoningIterationResponse(BaseModel):
+    iteration: int
+    section_ref: str
+    reason: str
+    section_text_length: int
+    can_answer: bool
+    response: str
+
+
+class ReasoningResultResponse(BaseModel):
+    answer: str
+    iterations: list[ReasoningIterationResponse]
+    converged: bool
+
+
+@router.post("/{doc_id}/reasoning", response_model=ReasoningResultResponse)
+async def run_reasoning(
+    doc_id: str, body: ReasoningRunRequest, request: Request
+) -> ReasoningResultResponse:
+    runner: ReasoningRunner | None = getattr(request.app.state, "reasoning_runner", None)
+    if runner is None or not runner.is_available:
+        raise HTTPException(
+            status_code=503,
+            detail=(
+                "Live reasoning disabled (REASONING_ENABLED=false or docling-agent not installed)"
+            ),
+        )
+
+    if not body.query.strip():
+        raise HTTPException(status_code=400, detail="Query must not be empty")
+
+    analysis_repo = getattr(request.app.state, "analysis_repo", None)
+    if analysis_repo is None:
+        raise HTTPException(status_code=500, detail="AnalysisRepository not wired")
+
+    latest = await analysis_repo.find_latest_completed_by_document(doc_id)
+    if latest is None or not latest.document_json:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No completed analysis with document_json for {doc_id}",
+        )
+
+    try:
+        result = await runner.run(
+            document_json=latest.document_json,
+            query=body.query,
+            model_id=body.model_id,
+        )
+    except ReasoningParseError as e:
+        # The upstream LLM couldn't produce a parseable answer after retries.
+        # 502 Bad Gateway — not our fault — with guidance the UI can show.
+        raise HTTPException(
+            status_code=502,
+            detail=(
+                f"The model '{e.model_id}' couldn't produce a parseable "
+                "answer after retries. Try a different model (e.g. "
+                "mistral-small3.2) or rephrase the question."
+            ),
+        ) from e
+    except Exception as e:
+        logger.exception("Reasoning loop failed for doc %s", doc_id)
+        raise HTTPException(status_code=500, detail=f"Reasoning loop failed: {e}") from e
+
+    return ReasoningResultResponse(
+        answer=result.answer,
+        iterations=[
+            ReasoningIterationResponse(
+                iteration=it.iteration,
+                section_ref=it.section_ref,
+                reason=it.reason,
+                section_text_length=it.section_text_length,
+                can_answer=it.can_answer,
+                response=it.response,
+            )
+            for it in result.iterations
+        ],
+        converged=result.converged,
+    )

document-parser/api/schemas.py

@@ -10,6 +10,11 @@ from datetime import datetime
 
 from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator
 
+# Document lifecycle status — currently single-state (uploaded). Kept as a
+# constant so future statuses (e.g. "archived", "deleted") can extend the
+# vocabulary without hunting magic strings across the codebase.
+DOCUMENT_STATUS_UPLOADED = "uploaded"
+
 
 def _to_camel(name: str) -> str:
     parts = name.split("_")
@@ -34,12 +39,19 @@ class HealthResponse(_CamelModel):
     database: str
     max_page_count: int | None = None
     max_file_size_mb: int | None = None
+    max_paste_image_size_mb: int | None = None
+    paste_allowed_image_types: list[str] = Field(default_factory=list)
+    ingestion_available: bool = False
+    # True when the live-reasoning runner (docling-agent + Ollama) is
+    # available: REASONING_ENABLED=true AND deps importable. Doesn't imply
+    # Ollama itself is reachable — that's checked per-call.
+    reasoning_available: bool = False
 
 
 class DocumentResponse(_CamelModel):
     id: str
     filename: str
-    status: str = "uploaded"  # Document status (always "uploaded" for now)
+    status: str = DOCUMENT_STATUS_UPLOADED
     content_type: str | None = None
     file_size: int | None = None
     page_count: int | None = None
@@ -158,6 +170,12 @@ class ChunkResponse(_CamelModel):
     source_page: int | None = None
     token_count: int = 0
     bboxes: list[ChunkBboxResponse] = []
+    modified: bool = False
+    deleted: bool = False
+
+
+class UpdateChunkTextRequest(BaseModel):
+    text: str
 
 
 class CreateAnalysisRequest(BaseModel):
@@ -174,3 +192,33 @@ class RechunkRequest(BaseModel):
     chunkingOptions: ChunkingOptionsRequest = Field(
         validation_alias=AliasChoices("chunkingOptions", "chunking_options")
     )
+
+
+class IngestionResponse(_CamelModel):
+    doc_id: str
+    chunks_indexed: int
+    embedding_dimension: int
+
+
+class IngestionStatusResponse(_CamelModel):
+    available: bool
+    opensearch_connected: bool = False
+
+
+class SearchResultItem(_CamelModel):
+    """A single search result with content and metadata."""
+
+    doc_id: str
+    filename: str
+    content: str
+    chunk_index: int
+    page_number: int
+    score: float
+    headings: list[str] = []
+    highlights: list[str] = []
+
+
+class SearchResponse(_CamelModel):
+    results: list[SearchResultItem]
+    total: int
+    query: str

document-parser/domain/ports.py

@@ -6,7 +6,7 @@ Infrastructure adapters (local Docling, Docling Serve, etc.) implement these.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
     from domain.models import AnalysisJob, Document
@@ -15,7 +15,25 @@ if TYPE_CHECKING:
         ChunkResult,
         ConversionOptions,
         ConversionResult,
+        LLMProviderType,
+        ReasoningResult,
     )
+    from domain.vector_schema import IndexedChunk, SearchResult
+
+
+class ReasoningParseError(Exception):
+    """Raised by a `ReasoningRunner` when the upstream LLM couldn't produce a
+    parseable answer after retries — e.g. docling-agent's known IndexError on
+    `find_json_dicts(...)[0]` when the model fails rejection-sampling.
+
+    Carries the model identifier so the API layer can surface it to the user
+    without leaking adapter internals.
+    """
+
+    def __init__(self, model_id: str, reason: str = "no parseable answer") -> None:
+        super().__init__(f"{model_id}: {reason}")
+        self.model_id = model_id
+        self.reason = reason
 
 
 class DocumentConverter(Protocol):
@@ -33,6 +51,15 @@ class DocumentConverter(Protocol):
         page_range: tuple[int, int] | None = None,
     ) -> ConversionResult: ...
 
+    @property
+    def supports_page_batching(self) -> bool:
+        """True if the orchestrator may slice a long document into page
+        batches (calling `convert` with a `page_range`) and merge the
+        results. Local in-process converters set this to True; remote
+        converters that handle batching themselves return False so the
+        orchestrator passes the full document through in one call."""
+        ...
+
 
 class DocumentChunker(Protocol):
     """Port for document chunking.
@@ -79,3 +106,135 @@ class AnalysisRepository(Protocol):
     async def delete(self, job_id: str) -> bool: ...
 
     async def delete_by_document(self, document_id: str) -> int: ...
+
+
+@runtime_checkable
+class EmbeddingService(Protocol):
+    """Port for text-to-vector embedding.
+
+    Implementations may call a local model, a remote microservice, etc.
+    """
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        """Generate embedding vectors for a batch of texts."""
+        ...
+
+
+@runtime_checkable
+class VectorStore(Protocol):
+    """Port for vector storage and retrieval.
+
+    Implementations (OpenSearch, pgvector, Qdrant, etc.) must satisfy this
+    contract. The port uses domain types from vector_schema — no infrastructure
+    details leak into the domain.
+    """
+
+    async def ensure_index(self, index_name: str, mapping: dict) -> None:
+        """Create the index if it does not exist. No-op if it already exists."""
+        ...
+
+    async def index_chunks(self, index_name: str, chunks: list[IndexedChunk]) -> int:
+        """Bulk-index a list of chunks. Returns the number of successfully indexed chunks."""
+        ...
+
+    async def search_similar(
+        self,
+        index_name: str,
+        embedding: list[float],
+        *,
+        k: int = 10,
+        doc_id: str | None = None,
+    ) -> list[SearchResult]:
+        """Find the k nearest chunks by embedding similarity.
+
+        Args:
+            index_name: Target index.
+            embedding: Query vector.
+            k: Number of results to return.
+            doc_id: If provided, restrict search to chunks from this document.
+        """
+        ...
+
+    async def get_chunks(
+        self,
+        index_name: str,
+        doc_id: str,
+        *,
+        limit: int = 1000,
+    ) -> list[SearchResult]:
+        """Retrieve all indexed chunks for a given document, ordered by chunk_index."""
+        ...
+
+    async def delete_document(self, index_name: str, doc_id: str) -> int:
+        """Delete all chunks for a document from the index. Returns count deleted."""
+        ...
+
+    async def ping(self) -> bool:
+        """Cheap reachability probe — True if the backing store responds.
+        Used by health checks; should not throw."""
+        ...
+
+
+@runtime_checkable
+class LLMProvider(Protocol):
+    """Connection-level abstraction over an LLM backend.
+
+    A provider carries the host/base-URL, the default model identifier, and a
+    type tag that adapters can dispatch on. The reasoning runner consumes a
+    provider — it doesn't construct one — so the runner stays decoupled from
+    Ollama-vs-OpenAI-vs-WatsonX wiring.
+
+    Today only `OllamaProvider` (in `infra/llm/`) is implemented because
+    docling-agent v0.1.0 is hardwired to Ollama via mellea's
+    `setup_local_session`. Adding a non-Ollama provider requires either
+    docling-agent upstream support or a fork (track
+    https://github.com/docling-project/docling-agent/issues/26 + provider
+    abstraction work upstream).
+    """
+
+    @property
+    def type(self) -> LLMProviderType: ...
+
+    @property
+    def host(self) -> str: ...
+
+    @property
+    def default_model_id(self) -> str: ...
+
+    def health_check(self) -> bool:
+        """Lightweight reachability probe. Returns True if the provider looks
+        usable. Implementations should be cheap (no model load, no inference).
+        """
+        ...
+
+
+@runtime_checkable
+class ReasoningRunner(Protocol):
+    """Port for live reasoning over a previously-converted document.
+
+    Takes the serialized DoclingDocument JSON + a user query + optional
+    per-call model override, returns a `ReasoningResult` (answer + iteration
+    trace + convergence flag).
+
+    Adapters MUST translate upstream parsing failures into
+    `ReasoningParseError`. Other exceptions propagate as-is — the API layer
+    maps them to 5xx.
+    """
+
+    @property
+    def is_available(self) -> bool:
+        """True if the runner can serve requests (deps importable + provider
+        wired). Used by the API layer to short-circuit with a 503 instead of
+        attempting a doomed call."""
+        ...
+
+    async def run(
+        self,
+        *,
+        document_json: str,
+        query: str,
+        model_id: str | None = None,
+    ) -> ReasoningResult:
+        """Execute the reasoning loop. `model_id` overrides the provider's
+        default for this call only."""
+        ...

document-parser/domain/value_objects.py

@@ -7,6 +7,11 @@ They have ZERO external dependencies (no docling, no HTTP, no DB).
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from enum import StrEnum
+
+# US Letter page dimensions (points) — fallback when page size is unknown
+DEFAULT_PAGE_WIDTH: float = 612.0
+DEFAULT_PAGE_HEIGHT: float = 792.0
 
 
 @dataclass(frozen=True)
@@ -15,6 +20,11 @@ class PageElement:
     bbox: list[float]
     content: str
     level: int = 0
+    # Docling `self_ref` ("#/texts/12", "#/tables/3", …). Empty for items
+    # that don't have one (rare — defensive default). Lets callers correlate
+    # a rendered bbox with the corresponding node in the graph without
+    # resorting to fuzzy bbox matching.
+    self_ref: str = ""
 
 
 @dataclass(frozen=True)
@@ -71,6 +81,14 @@ class ChunkBbox:
     bbox: list[float]  # [left, top, right, bottom] in TOPLEFT origin
 
 
+@dataclass(frozen=True)
+class ChunkDocItem:
+    """Source element referenced by a chunk. Enables Neo4j DERIVED_FROM edges."""
+
+    self_ref: str
+    label: str
+
+
 @dataclass(frozen=True)
 class ChunkResult:
     text: str
@@ -78,3 +96,44 @@ class ChunkResult:
     source_page: int | None = None
     token_count: int = 0
     bboxes: list[ChunkBbox] = field(default_factory=list)
+    doc_items: list[ChunkDocItem] = field(default_factory=list)
+
+
+# --- Reasoning (live docling-agent runner) -----------------------------------
+
+
+class LLMProviderType(StrEnum):
+    """LLM backends the reasoning runner can talk to.
+
+    Today only OLLAMA is realizable: docling-agent v0.1.0 is hardwired to
+    Ollama via mellea's `setup_local_session`. Other variants are kept here
+    to make the abstraction visible and prepare future backends — adding one
+    requires either docling-agent upstream support (see
+    https://github.com/docling-project/docling-agent/issues/26) or a fork.
+    """
+
+    OLLAMA = "ollama"
+
+
+@dataclass(frozen=True)
+class ReasoningIteration:
+    """One step of the reasoning loop — section the agent visited and what
+    it concluded. Mirrors the upstream docling-agent `RAGIteration` shape so
+    serialization stays 1:1 with externally-produced traces."""
+
+    iteration: int
+    section_ref: str
+    reason: str
+    section_text_length: int
+    can_answer: bool
+    response: str
+
+
+@dataclass(frozen=True)
+class ReasoningResult:
+    """Full output of a reasoning run: final answer, the path the agent
+    walked through the document, and whether the loop converged."""
+
+    answer: str
+    iterations: list[ReasoningIteration]
+    converged: bool

document-parser/domain/vector_schema.py

@@ -0,0 +1,177 @@
+"""Vector index schema — data contract for OpenSearch ingestion and inspection.
+
+This module defines the standard metadata schema for the vector index used by
+the ingestion pipeline (0.4.0) and the inspection UI (0.5.0).
+
+Field usage by milestone:
+    ┌────────────┬────────────────────────┬───────────────────────────────┬──────────────┐
+    │ Field      │ 0.4.0 (write)          │ 0.5.0 (read)                  │ Source       │
+    ├────────────┼────────────────────────┼───────────────────────────────┼──────────────┤
+    │ content    │ Full-text search       │ Chunk panel display           │ Docling std  │
+    │ embedding  │ Indexed                │ kNN semantic search           │ Docling std  │
+    │ doc_items  │ Indexed                │ Element type filtering        │ Docling std  │
+    │ headings   │ Indexed                │ Section hierarchy display     │ Docling std  │
+    │ origin     │ Indexed                │ Document provenance           │ Docling std  │
+    │ bboxes     │ Written at ingestion   │ Chunk↔bbox highlight          │ Studio       │
+    │ page_number│ Written at ingestion   │ Split view navigation         │ Studio       │
+    │ chunk_index│ Written at ingestion   │ Chunk ordering in panel       │ Studio       │
+    │ chunk_type │ Written at ingestion   │ Metadata panel                │ Studio       │
+    │ doc_id     │ Document linking       │ Document list navigation      │ Studio       │
+    │ filename   │ "My Documents" list    │ Display                       │ Studio       │
+    └────────────┴────────────────────────┴───────────────────────────────┴──────────────┘
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# -- Value objects for a single indexed chunk ----------------------------------
+
+DEFAULT_EMBEDDING_DIMENSION = 384  # Granite Embedding 30M (sentence-transformers)
+DEFAULT_INDEX_NAME = "docling-studio-chunks"
+
+
+@dataclass(frozen=True)
+class ChunkBboxEntry:
+    """Bounding box for a chunk region on a specific page."""
+
+    page: int
+    x: float
+    y: float
+    w: float
+    h: float
+
+
+@dataclass(frozen=True)
+class DocItemRef:
+    """Reference to a Docling DocItem (element in the document structure)."""
+
+    self_ref: str
+    label: str  # text, table, picture, list, etc.
+
+
+@dataclass(frozen=True)
+class ChunkOrigin:
+    """Provenance metadata — links a chunk back to its source document binary."""
+
+    binary_hash: str
+    filename: str
+
+
+@dataclass(frozen=True)
+class IndexedChunk:
+    """A single chunk ready to be indexed in the vector store.
+
+    This is the domain-level representation of a document in the OpenSearch index.
+    It combines Docling-standard fields (content, embedding, doc_items, headings,
+    origin) with Docling Studio enriched fields (bboxes, page_number, chunk_index,
+    chunk_type, doc_id, filename).
+    """
+
+    doc_id: str
+    filename: str
+    content: str
+    embedding: list[float]
+    chunk_index: int
+    chunk_type: str  # text, table, picture, list, etc.
+    page_number: int
+    bboxes: list[ChunkBboxEntry] = field(default_factory=list)
+    headings: list[str] = field(default_factory=list)
+    doc_items: list[DocItemRef] = field(default_factory=list)
+    origin: ChunkOrigin | None = None
+
+    def to_dict(self) -> dict:
+        """Serialize to a dict matching the OpenSearch index mapping."""
+        result: dict = {
+            "doc_id": self.doc_id,
+            "filename": self.filename,
+            "content": self.content,
+            "embedding": self.embedding,
+            "chunk_index": self.chunk_index,
+            "chunk_type": self.chunk_type,
+            "page_number": self.page_number,
+            "bboxes": [
+                {"page": b.page, "x": b.x, "y": b.y, "w": b.w, "h": b.h} for b in self.bboxes
+            ],
+            "headings": self.headings,
+            "doc_items": [{"self_ref": d.self_ref, "label": d.label} for d in self.doc_items],
+        }
+        if self.origin:
+            result["origin"] = {
+                "binary_hash": self.origin.binary_hash,
+                "filename": self.origin.filename,
+            }
+        return result
+
+
+# -- Search result -------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    """A chunk returned from a vector store query."""
+
+    chunk: IndexedChunk
+    score: float  # similarity score (higher = more similar)
+
+
+# -- Index mapping template ----------------------------------------------------
+
+
+def build_index_mapping(embedding_dimension: int = DEFAULT_EMBEDDING_DIMENSION) -> dict:
+    """Build the OpenSearch index mapping for the chunk index.
+
+    Args:
+        embedding_dimension: Vector dimension for the knn_vector field.
+            Defaults to 384 (Granite Embedding 30M / all-MiniLM-L6-v2).
+    """
+    return {
+        "settings": {
+            "index": {
+                "knn": True,
+            },
+        },
+        "mappings": {
+            "properties": {
+                "doc_id": {"type": "keyword"},
+                "filename": {"type": "keyword"},
+                "content": {"type": "text", "analyzer": "standard"},
+                "embedding": {
+                    "type": "knn_vector",
+                    "dimension": embedding_dimension,
+                    "method": {
+                        "engine": "faiss",
+                        "name": "hnsw",
+                    },
+                },
+                "chunk_index": {"type": "integer"},
+                "chunk_type": {"type": "keyword"},
+                "page_number": {"type": "integer"},
+                "bboxes": {
+                    "type": "nested",
+                    "properties": {
+                        "page": {"type": "integer"},
+                        "x": {"type": "float"},
+                        "y": {"type": "float"},
+                        "w": {"type": "float"},
+                        "h": {"type": "float"},
+                    },
+                },
+                "headings": {"type": "text"},
+                "doc_items": {
+                    "type": "nested",
+                    "properties": {
+                        "self_ref": {"type": "keyword"},
+                        "label": {"type": "keyword"},
+                    },
+                },
+                "origin": {
+                    "type": "object",
+                    "properties": {
+                        "binary_hash": {"type": "keyword"},
+                        "filename": {"type": "keyword"},
+                    },
+                },
+            },
+        },
+    }

document-parser/infra/docling_agent_reasoning.py

@@ -0,0 +1,129 @@
+"""docling-agent reasoning runner adapter.
+
+Implements `ReasoningRunner` for an `OllamaProvider`-backed `LLMProvider`.
+Encapsulates everything that talks to docling-agent / mellea so neither the
+domain nor the API layer depends on those packages.
+
+Why we still call the private `_rag_loop`: `DoclingRAGAgent.run()` wraps the
+answer in a synthetic `DoclingDocument` and discards the iteration trace.
+Tracked upstream at https://github.com/docling-project/docling-agent/issues/26
+— switch to the public surface once the issue lands.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+
+from domain.ports import LLMProvider, ReasoningParseError
+from domain.value_objects import (
+    LLMProviderType,
+    ReasoningIteration,
+    ReasoningResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def deps_present() -> bool:
+    """Import-check for the heavy reasoning deps. Used by the DI wire-up to
+    decide whether to instantiate the runner at all (so the backend boots
+    cleanly when docling-agent + mellea aren't installed)."""
+    try:
+        import docling_agent.agents  # noqa: F401
+        import mellea  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+class DoclingAgentReasoningRunner:
+    """ReasoningRunner adapter wrapping docling-agent + mellea.
+
+    The provider's host is committed to the process-wide `OLLAMA_HOST` env
+    var at construction time — Ollama's Python client reads it on session
+    creation. Setting it once at boot (instead of per-request) eliminates the
+    cross-request race the previous implementation exposed.
+    """
+
+    def __init__(self, provider: LLMProvider) -> None:
+        if provider.type is not LLMProviderType.OLLAMA:
+            raise NotImplementedError(
+                f"docling-agent v0.1.0 only supports Ollama, got provider type "
+                f"{provider.type!r}. See "
+                f"https://github.com/docling-project/docling-agent/issues/26"
+            )
+        self._provider = provider
+        self._deps_ok = deps_present()
+        # Commit the host at boot — concurrent `run()` calls then share the
+        # same value with no racy mutation.
+        os.environ["OLLAMA_HOST"] = provider.host
+
+    @property
+    def is_available(self) -> bool:
+        return self._deps_ok
+
+    async def run(
+        self,
+        *,
+        document_json: str,
+        query: str,
+        model_id: str | None = None,
+    ) -> ReasoningResult:
+        if not self._deps_ok:
+            raise RuntimeError("docling-agent / mellea not importable — cannot run reasoning")
+
+        # Lazy imports keep the module loadable when deps are missing (the
+        # runner is only ever instantiated when `deps_present()` is True, but
+        # this also makes the import surface explicit).
+        from docling_agent.agents import DoclingRAGAgent
+        from docling_core.types.doc.document import DoclingDocument
+        from mellea.backends.model_ids import ModelIdentifier
+
+        raw_model_id = model_id or self._provider.default_model_id
+        # `DoclingRAGAgent` (pydantic) validates `model_id` strictly against
+        # `ModelIdentifier` from mellea. Wrapping on the Ollama axis is the
+        # only realizable path today (cf. LLMProvider docstring).
+        wrapped_model_id = ModelIdentifier(ollama_name=raw_model_id)
+
+        try:
+            doc = DoclingDocument.model_validate_json(document_json)
+        except Exception as e:
+            raise RuntimeError(f"Failed to parse document_json: {e}") from e
+
+        agent = DoclingRAGAgent(model_id=wrapped_model_id, tools=[])
+        logger.info(
+            "Reasoning run: model_id=%s ollama_host=%s query=%r",
+            raw_model_id,
+            self._provider.host,
+            query[:120],
+        )
+
+        try:
+            # `_rag_loop` is sync + LLM-heavy (N * model latency). Offload to
+            # a worker thread so concurrent calls don't block the event loop.
+            # Private API kept until docling-agent#26 lands.
+            raw_result = await asyncio.to_thread(agent._rag_loop, query=query, doc=doc)
+        except IndexError as e:
+            # docling-agent v0.1.0 bug: `_attempt_answer` / `_select_section`
+            # call `find_json_dicts(answer.value)[0]` without handling an
+            # empty list. When the model can't produce a parseable JSON after
+            # 3 rejection-sampling retries + 3 `select_from_failure` retries,
+            # the list is empty and `[0]` raises IndexError. Translate to a
+            # domain-level error the API can map to 502.
+            logger.warning(
+                "docling-agent produced no parseable JSON for model=%s query=%r",
+                raw_model_id,
+                query[:120],
+            )
+            raise ReasoningParseError(
+                model_id=raw_model_id,
+                reason="no parseable answer after retries",
+            ) from e
+
+        return ReasoningResult(
+            answer=raw_result.answer,
+            iterations=[ReasoningIteration(**it.model_dump()) for it in raw_result.iterations],
+            converged=raw_result.converged,
+        )

document-parser/infra/docling_graph.py

@@ -0,0 +1,178 @@
+"""Build a Cytoscape-shaped graph payload straight from a serialized
+`DoclingDocument` (i.e. the `document_json` blob stored in SQLite).
+
+Mirrors `infra.neo4j.queries.fetch_graph` so the frontend can reuse the same
+`GraphView` component — the only intentional difference is the absence of
+Chunk nodes / HAS_CHUNK / DERIVED_FROM edges, since chunks are a product of
+the Maintain step and don't exist in `document_json` alone.
+
+Used by the reasoning-trace viewer, which needs the structural graph to
+overlay iterations onto but does NOT need (and should not require) Neo4j.
+"""
+
+from __future__ import annotations
+
+import json
+from itertools import pairwise
+from typing import Any
+
+from infra.docling_tree import (
+    build_collapse_index,
+    dfs_order,
+    element_label,
+    is_inline_group,
+    iter_items,
+    iter_pages,
+    iter_provs,
+    parent_ref,
+)
+from infra.neo4j.queries import GraphPayload
+
+
+def _element_node(
+    doc_id: str,
+    item: dict[str, Any],
+    provs: list[dict[str, Any]],
+    *,
+    text_override: str | None = None,
+) -> dict[str, Any]:
+    first_page = provs[0].get("page_no") if provs else None
+    raw_text = text_override if text_override is not None else (item.get("text") or "")
+    return {
+        "id": f"elem::{item.get('self_ref')}",
+        "group": "element",
+        "label": element_label(item.get("label") or ""),
+        "docling_label": (item.get("label") or "").lower(),
+        "self_ref": item.get("self_ref"),
+        "text": raw_text[:200],
+        "prov_page": first_page,
+        "provs": provs,
+        "level": item.get("level"),
+        "doc_id": doc_id,
+    }
+
+
+def _page_node(doc_id: str, page: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": f"page::{page.get('page_no')}",
+        "group": "page",
+        "page_no": page.get("page_no"),
+        "width": page.get("width"),
+        "height": page.get("height"),
+        "doc_id": doc_id,
+    }
+
+
+def _edge(source: str, target: str, edge_type: str, *, order: int | None = None) -> dict[str, Any]:
+    return {
+        "id": f"{edge_type}::{source}::{target}",
+        "source": source,
+        "target": target,
+        "type": edge_type,
+        "order": order,
+    }
+
+
+def build_graph_payload(
+    document_json: str,
+    *,
+    doc_id: str,
+    title: str | None = None,
+    max_pages: int = 200,
+) -> GraphPayload:
+    """Build a `GraphPayload` equivalent to `fetch_graph(neo4j, doc_id)` from
+    the raw `DoclingDocument` JSON.
+
+    Returns `truncated=True` with empty node/edge lists beyond `max_pages`, so
+    the caller can mirror the Neo4j endpoint's 413 behavior.
+    """
+    doc_data = json.loads(document_json)
+
+    pages_raw = list(iter_pages(doc_data))
+    page_count = len(pages_raw)
+    if page_count > max_pages:
+        return GraphPayload(
+            doc_id=doc_id,
+            nodes=[],
+            edges=[],
+            node_count=0,
+            edge_count=0,
+            truncated=True,
+            page_count=page_count,
+        )
+
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+
+    doc_node_id = f"doc::{doc_id}"
+    nodes.append(
+        {
+            "id": doc_node_id,
+            "group": "document",
+            "doc_id": doc_id,
+            "title": title,
+            # `stages_applied` is a Neo4j-only artifact; keep the key present
+            # for shape parity but leave it empty since SQLite doesn't track it.
+            "stages_applied": [],
+        }
+    )
+
+    # Page nodes.
+    for p in pages_raw:
+        nodes.append(_page_node(doc_id, p))
+
+    # Issue #197: collapse Docling noise — InlineGroup style runs and the
+    # internal text labels Docling extracts from pictures/charts.
+    skip_refs, inline_meta = build_collapse_index(doc_data)
+
+    # Element nodes + collect parent/body metadata for edges below. The
+    # `element_idx` mirrors TreeWriter's `enumerate(elements)` so PARENT_OF
+    # carries the same `order` the Neo4j projection does.
+    by_ref: dict[str, dict[str, Any]] = {}
+    element_idx = 0
+    for _, item in iter_items(doc_data):
+        ref = item.get("self_ref")
+        if not ref or ref in skip_refs:
+            continue
+        by_ref[ref] = item
+        if is_inline_group(item):
+            meta = inline_meta.get(ref, {"text": "", "provs": []})
+            provs = meta["provs"]
+            text_override: str | None = meta["text"]
+        else:
+            provs = iter_provs(item)
+            text_override = None
+        nodes.append(_element_node(doc_id, item, provs, text_override=text_override))
+
+        pref = parent_ref(item)
+        if pref == "#/body":
+            edges.append(_edge(doc_node_id, f"elem::{ref}", "HAS_ROOT"))
+        elif pref:
+            edges.append(_edge(f"elem::{pref}", f"elem::{ref}", "PARENT_OF", order=element_idx))
+
+        # ON_PAGE, dedup'd per (element, page) — matches the Neo4j query's
+        # DISTINCT projection through Provenance.
+        seen_pages: set[int] = set()
+        for prov in provs:
+            page_no = prov.get("page_no")
+            if page_no is None or page_no in seen_pages:
+                continue
+            seen_pages.add(page_no)
+            edges.append(_edge(f"elem::{ref}", f"page::{page_no}", "ON_PAGE"))
+
+        element_idx += 1
+
+    # NEXT chain (DFS pre-order from body), inline-group children skipped.
+    for a, b in pairwise(dfs_order(doc_data, skip_refs)):
+        if a in by_ref and b in by_ref:
+            edges.append(_edge(f"elem::{a}", f"elem::{b}", "NEXT"))
+
+    return GraphPayload(
+        doc_id=doc_id,
+        nodes=nodes,
+        edges=edges,
+        node_count=len(nodes),
+        edge_count=len(edges),
+        truncated=False,
+        page_count=page_count,
+    )

document-parser/infra/docling_tree.py

@@ -0,0 +1,276 @@
+"""Pure helpers over a serialized `DoclingDocument` dict.
+
+No I/O, no Neo4j. Shared between:
+- `infra.neo4j.tree_writer` — persists the tree into Neo4j during the Maintain
+  step (IngestionPipeline).
+- `infra.docling_graph` — builds an in-memory `GraphPayload` from the SQLite
+  `document_json` blob for the reasoning-trace viewer.
+
+Keep this module the single source of truth for how we read Docling's own
+structure, so the two consumers can't drift.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+# Docling label -> specific Neo4j/Cytoscape label. Every element carries the
+# generic :Element tag too. Kept 1:1 with docling-core's label taxonomy so the
+# projection is a faithful mirror of the DoclingDocument.
+LABEL_MAP: dict[str, str] = {
+    "section_header": "SectionHeader",
+    "title": "SectionHeader",
+    "paragraph": "Paragraph",
+    "text": "Paragraph",
+    "list_item": "ListItem",
+    "list": "List",  # distinct from :ListItem — a list is a container
+    "inline": "Paragraph",  # see issue #197 — collapsed into one paragraph node
+    "table": "Table",
+    "picture": "Figure",
+    "formula": "Formula",
+    "code": "Code",
+    "caption": "Caption",
+    "footnote": "Footnote",
+    "page_header": "PageHeader",
+    "page_footer": "PageFooter",
+    "key_value_area": "KeyValueArea",
+    "form_area": "FormArea",
+    "document_index": "DocumentIndex",
+}
+DEFAULT_LABEL = "TextElement"
+
+
+def element_label(docling_label: str) -> str:
+    return LABEL_MAP.get(docling_label.lower(), DEFAULT_LABEL)
+
+
+def is_inline_group(item: dict[str, Any]) -> bool:
+    """True iff `item` is a Docling InlineGroup (paragraph of mixed style runs).
+
+    Docling represents an inline-styled paragraph as one entry in `groups[]`
+    (label `inline`) plus N entries in `texts[]` (label `text`), one per style
+    run. We collapse them into a single Paragraph projection — see #197.
+    """
+    return (item.get("label") or "").lower() == "inline"
+
+
+def is_picture(item: dict[str, Any]) -> bool:
+    """True iff `item` is a Docling PictureItem (figure or chart).
+
+    A `picture` keeps its node in the graph (it IS the figure), but its
+    `children` — internal text labels extracted from a flowchart, diagram,
+    chart axis labels — are noise for graph readability and are skipped.
+    Captions live in a separate `captions` field on the picture, not in
+    `children`, so they are unaffected by this skip.
+    """
+    return (item.get("label") or "").lower() in {"picture", "chart"}
+
+
+def iter_items(doc_data: dict[str, Any]) -> Iterator[tuple[str, dict[str, Any]]]:
+    """Yield every item from texts/tables/pictures/groups with its source list key."""
+    for key in ("texts", "tables", "pictures", "groups"):
+        for item in doc_data.get(key, []) or []:
+            yield key, item
+
+
+def parent_ref(item: dict[str, Any]) -> str | None:
+    parent = item.get("parent")
+    if isinstance(parent, dict):
+        return parent.get("$ref") or parent.get("cref")
+    return None
+
+
+def iter_provs(item: dict[str, Any]) -> list[dict[str, Any]]:
+    """Flatten a Docling item's `prov[]` into a list of dict rows.
+
+    A single item may have multiple provs when it spans page breaks or appears
+    more than once in the layout. The returned dicts carry the original index
+    under `order` so sequence is preserved.
+    """
+    provs = item.get("prov") or []
+    rows: list[dict[str, Any]] = []
+    for idx, p in enumerate(provs):
+        bbox = p.get("bbox")
+        l_, t_, r_, b_ = 0.0, 0.0, 0.0, 0.0
+        if isinstance(bbox, dict):
+            l_ = float(bbox.get("l", 0.0) or 0.0)
+            t_ = float(bbox.get("t", 0.0) or 0.0)
+            r_ = float(bbox.get("r", 0.0) or 0.0)
+            b_ = float(bbox.get("b", 0.0) or 0.0)
+        elif isinstance(bbox, list | tuple) and len(bbox) >= 4:
+            l_, t_, r_, b_ = (float(x) for x in bbox[:4])
+        coord_origin = (bbox.get("coord_origin") if isinstance(bbox, dict) else None) or "TOPLEFT"
+        charspan = p.get("charspan") or []
+        rows.append(
+            {
+                "order": idx,
+                "page_no": p.get("page_no"),
+                "bbox_l": l_,
+                "bbox_t": t_,
+                "bbox_r": r_,
+                "bbox_b": b_,
+                "coord_origin": coord_origin,
+                "charspan_start": int(charspan[0]) if len(charspan) >= 1 else None,
+                "charspan_end": int(charspan[1]) if len(charspan) >= 2 else None,
+            }
+        )
+    return rows
+
+
+def dfs_order(doc_data: dict[str, Any], skip_refs: set[str] | None = None) -> list[str]:
+    """Return `self_ref`s in reading order (DFS pre-order from body).
+
+    `skip_refs` (typically the set returned by `build_inline_index`) is omitted
+    from the chain. Inline groups themselves are emitted but the walk does not
+    recurse into their style-run children, so the resulting order references
+    only nodes that survive the InlineGroup collapse.
+    """
+    skip = skip_refs or set()
+    by_ref: dict[str, dict[str, Any]] = {}
+    for _, item in iter_items(doc_data):
+        ref = item.get("self_ref")
+        if ref:
+            by_ref[ref] = item
+    body = doc_data.get("body") or {}
+    order: list[str] = []
+
+    def walk(children: list[dict[str, Any]] | None) -> None:
+        if not children:
+            return
+        for ch in children:
+            ref = ch.get("$ref") or ch.get("cref")
+            if not ref or ref in skip:
+                continue
+            order.append(ref)
+            child = by_ref.get(ref)
+            if child and not is_inline_group(child):
+                walk(child.get("children"))
+
+    walk(body.get("children"))
+    return order
+
+
+def build_collapse_index(
+    doc_data: dict[str, Any],
+) -> tuple[set[str], dict[str, dict[str, Any]]]:
+    """Pre-compute graph-projection collapses for a serialized DoclingDocument.
+
+    Two cases produce noise nodes if mirrored 1:1 — see issue #197:
+
+    1. **InlineGroup** — Docling emits one `groups[]` entry (label `inline`)
+       plus N `texts[]` style runs. We collapse the children into the group,
+       which is then projected as a single `:Paragraph` with concatenated
+       text and the union of children's provs.
+    2. **Picture / Chart** — internal text labels extracted from flowcharts,
+       diagrams or chart axes hang off the picture's `children`. The picture
+       node itself stays, but its descendants are skipped so the graph isn't
+       drowned in dozens of tiny labels.
+
+    Returns `(skip_refs, inline_meta)`:
+
+    - `skip_refs`: every `self_ref` to drop from element / edge projections.
+    - `inline_meta[group_ref]`: `{"text": str, "provs": list[dict]}` —
+      override values for the inline group projection. Pictures don't have
+      an entry here; they keep their own text/prov.
+    """
+    by_ref: dict[str, dict[str, Any]] = {}
+    for _, item in iter_items(doc_data):
+        ref = item.get("self_ref")
+        if ref:
+            by_ref[ref] = item
+
+    skip_refs: set[str] = set()
+    inline_meta: dict[str, dict[str, Any]] = {}
+
+    for item in by_ref.values():
+        ref = item.get("self_ref") or ""
+        if not ref:
+            continue
+        if is_inline_group(item):
+            text_parts, provs = _collect_inline_descendants(ref, by_ref, skip_refs)
+            # Re-index prov order so the resulting :Provenance nodes are 0..N-1
+            # contiguous instead of carrying each child's individual indices.
+            for idx, prov in enumerate(provs):
+                prov["order"] = idx
+            inline_meta[ref] = {
+                "text": " ".join(text_parts),
+                "provs": provs,
+            }
+        elif is_picture(item):
+            _collect_descendants(ref, by_ref, skip_refs)
+
+    return skip_refs, inline_meta
+
+
+def _collect_descendants(
+    root_ref: str,
+    by_ref: dict[str, dict[str, Any]],
+    skip_refs: set[str],
+) -> None:
+    """DFS `root_ref`'s subtree and add every descendant to `skip_refs`.
+
+    Used for picture children — we just want them dropped, not aggregated.
+    """
+
+    def walk(ref: str) -> None:
+        item = by_ref.get(ref)
+        if item is None:
+            return
+        for ch in item.get("children") or []:
+            child_ref = ch.get("$ref") or ch.get("cref")
+            if not child_ref or child_ref in skip_refs:
+                continue
+            skip_refs.add(child_ref)
+            walk(child_ref)
+
+    walk(root_ref)
+
+
+def _collect_inline_descendants(
+    group_ref: str,
+    by_ref: dict[str, dict[str, Any]],
+    skip_refs: set[str],
+) -> tuple[list[str], list[dict[str, Any]]]:
+    """DFS an inline group's subtree, returning its text parts and provs in
+    document order. `skip_refs` is mutated with every visited descendant."""
+    text_parts: list[str] = []
+    provs: list[dict[str, Any]] = []
+
+    def walk(ref: str) -> None:
+        item = by_ref.get(ref)
+        if item is None:
+            return
+        for ch in item.get("children") or []:
+            child_ref = ch.get("$ref") or ch.get("cref")
+            if not child_ref or child_ref in skip_refs:
+                continue
+            skip_refs.add(child_ref)
+            child = by_ref.get(child_ref)
+            if child is None:
+                continue
+            if is_inline_group(child):
+                walk(child_ref)
+                continue
+            text = child.get("text") or ""
+            if text:
+                text_parts.append(text)
+            provs.extend(iter_provs(child))
+
+    walk(group_ref)
+    return text_parts, provs
+
+
+def iter_pages(doc_data: dict[str, Any]) -> Iterator[dict[str, Any]]:
+    """Yield page dicts with `page_no`, `width`, `height` from the `pages` map."""
+    for page_no_str, page_obj in (doc_data.get("pages") or {}).items():
+        try:
+            page_no = int(page_no_str)
+        except (TypeError, ValueError):
+            continue
+        size = (page_obj or {}).get("size") or {}
+        yield {
+            "page_no": page_no,
+            "width": size.get("width"),
+            "height": size.get("height"),
+        }

document-parser/infra/embedding_client.py

@@ -0,0 +1,51 @@
+"""HTTP client adapter for the embedding microservice.
+
+Satisfies the ``EmbeddingService`` Protocol defined in ``domain.ports``.
+Calls the embedding-service REST API (POST /embed).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Maximum texts per request to avoid payload / memory issues on the server.
+_MAX_BATCH = 256
+
+
+class EmbeddingClient:
+    """Remote embedding adapter backed by the embedding-service microservice.
+
+    Args:
+        base_url: Embedding service URL (e.g. ``http://localhost:8001``).
+        timeout: HTTP request timeout in seconds.
+    """
+
+    def __init__(self, base_url: str, *, timeout: float = 120.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings by calling the remote service.
+
+        Automatically splits large batches into sub-batches of ``_MAX_BATCH``.
+        """
+        if not texts:
+            return []
+
+        all_embeddings: list[list[float]] = []
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            for start in range(0, len(texts), _MAX_BATCH):
+                batch = texts[start : start + _MAX_BATCH]
+                resp = await client.post(
+                    f"{self._base_url}/embed",
+                    json={"texts": batch},
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                all_embeddings.extend(data["embeddings"])
+
+        return all_embeddings

document-parser/infra/llm/ollama_provider.py

@@ -0,0 +1,47 @@
+"""Ollama LLM provider adapter.
+
+Implements `LLMProvider` for a locally-reachable Ollama instance. Holds the
+host URL + default model id; exposes a cheap `health_check` (HEAD `/api/tags`)
+that doesn't load any model.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from domain.value_objects import LLMProviderType
+
+logger = logging.getLogger(__name__)
+
+# Ollama's tags endpoint returns 200 with an empty list even on a fresh
+# install — perfect for a "is the daemon up?" probe.
+_HEALTH_PATH = "/api/tags"
+_HEALTH_TIMEOUT_SECONDS = 1.5
+
+
+class OllamaProvider:
+    def __init__(self, host: str, default_model_id: str) -> None:
+        self._host = host.rstrip("/")
+        self._default_model_id = default_model_id
+
+    @property
+    def type(self) -> LLMProviderType:
+        return LLMProviderType.OLLAMA
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def default_model_id(self) -> str:
+        return self._default_model_id
+
+    def health_check(self) -> bool:
+        try:
+            resp = httpx.get(f"{self._host}{_HEALTH_PATH}", timeout=_HEALTH_TIMEOUT_SECONDS)
+        except httpx.HTTPError as e:
+            logger.debug("Ollama health check failed for %s: %s", self._host, e)
+            return False
+        return resp.status_code == 200

document-parser/infra/local_chunker.py

@@ -15,7 +15,7 @@ from docling_core.transforms.chunker import HierarchicalChunker
 from docling_core.transforms.chunker.hybrid_chunker import HybridChunker
 from docling_core.types.doc.document import DoclingDocument
 
-from domain.value_objects import ChunkBbox, ChunkingOptions, ChunkResult
+from domain.value_objects import ChunkBbox, ChunkDocItem, ChunkingOptions, ChunkResult
 from infra.bbox import EMPTY_BBOX, to_topleft_list
 
 logger = logging.getLogger(__name__)
@@ -39,9 +39,18 @@ def _chunk_sync(document_json: str, options: ChunkingOptions) -> list[ChunkResul
         source_page = None
         token_count = 0
         bboxes: list[ChunkBbox] = []
+        doc_items: list[ChunkDocItem] = []
 
         if hasattr(chunk, "meta") and chunk.meta and chunk.meta.doc_items:
             for doc_item in chunk.meta.doc_items:
+                ref = getattr(doc_item, "self_ref", None)
+                if ref:
+                    doc_items.append(
+                        ChunkDocItem(
+                            self_ref=ref,
+                            label=str(getattr(doc_item, "label", "") or ""),
+                        )
+                    )
                 if not hasattr(doc_item, "prov") or not doc_item.prov:
                     continue
                 for prov in doc_item.prov:
@@ -67,6 +76,7 @@ def _chunk_sync(document_json: str, options: ChunkingOptions) -> list[ChunkResul
                 source_page=source_page,
                 token_count=token_count,
                 bboxes=bboxes,
+                doc_items=doc_items,
             )
         )
 

document-parser/infra/local_converter.py

@@ -36,6 +36,8 @@ from docling_core.types.doc import (
 )
 
 from domain.value_objects import (
+    DEFAULT_PAGE_HEIGHT,
+    DEFAULT_PAGE_WIDTH,
     ConversionOptions,
     ConversionResult,
     PageDetail,
@@ -50,10 +52,6 @@ logger = logging.getLogger(__name__)
 # Uses a timeout to prevent a frozen conversion from blocking all others.
 _converter_lock = threading.Lock()
 
-# US Letter page dimensions (points) — fallback when page size is unknown
-_DEFAULT_PAGE_WIDTH = 612.0
-_DEFAULT_PAGE_HEIGHT = 792.0
-
 # Default converter (lazy-init on first request)
 _default_converter: DoclingConverter | None = None
 
@@ -175,11 +173,11 @@ def _process_content_item(
                 logger.warning(
                     "Page %d not found in document metadata — using US Letter fallback (%sx%s pt)",
                     page_no,
-                    _DEFAULT_PAGE_WIDTH,
+                    DEFAULT_PAGE_WIDTH,
-                    _DEFAULT_PAGE_HEIGHT,
+                    DEFAULT_PAGE_HEIGHT,
                 )
                 pages[page_no] = PageDetail(
-                    page_number=page_no, width=_DEFAULT_PAGE_WIDTH, height=_DEFAULT_PAGE_HEIGHT
+                    page_number=page_no, width=DEFAULT_PAGE_WIDTH, height=DEFAULT_PAGE_HEIGHT
                 )
 
             page_height = pages[page_no].height
@@ -196,7 +194,13 @@ def _process_content_item(
                     content = item.export_to_markdown()
 
             pages[page_no].elements.append(
-                PageElement(type=element_type, bbox=bbox, content=content, level=level)
+                PageElement(
+                    type=element_type,
+                    bbox=bbox,
+                    content=content,
+                    level=level,
+                    self_ref=getattr(item, "self_ref", "") or "",
+                )
             )
         except (AttributeError, KeyError, TypeError, ValueError):
             logger.warning(
@@ -248,10 +252,10 @@ def _convert_sync(
         pages_detail = [
             PageDetail(
                 page_number=i + 1,
-                width=doc.pages[i + 1].size.width if (i + 1) in doc.pages else _DEFAULT_PAGE_WIDTH,
+                width=doc.pages[i + 1].size.width if (i + 1) in doc.pages else DEFAULT_PAGE_WIDTH,
                 height=doc.pages[i + 1].size.height
                 if (i + 1) in doc.pages
-                else _DEFAULT_PAGE_HEIGHT,
+                else DEFAULT_PAGE_HEIGHT,
             )
             for i in range(page_count)
         ]
@@ -277,6 +281,10 @@ def _convert_sync(
 class LocalConverter:
     """Adapter that runs Docling locally as a Python library."""
 
+    # In-process — the orchestrator may slice long docs into page batches
+    # and merge results (cf. AnalysisService._run_batched_conversion).
+    supports_page_batching: bool = True
+
     async def convert(
         self,
         file_path: str,

document-parser/infra/neo4j/__init__.py

@@ -0,0 +1,31 @@
+"""Neo4j storage adapter — graph-native document structure.
+
+Provides a thin driver wrapper, idempotent schema bootstrap, and
+walkers between DoclingDocument and the graph model.
+"""
+
+from infra.neo4j.chunk_writer import ChunkWriteResult, write_chunks
+from infra.neo4j.driver import Neo4jDriver, close_driver, get_driver
+from infra.neo4j.queries import fetch_graph
+from infra.neo4j.schema import bootstrap_schema
+from infra.neo4j.tree_reader import (
+    delete_document,
+    document_exists,
+    read_document_json,
+)
+from infra.neo4j.tree_writer import TreeWriteResult, write_document
+
+__all__ = [
+    "ChunkWriteResult",
+    "Neo4jDriver",
+    "TreeWriteResult",
+    "bootstrap_schema",
+    "close_driver",
+    "delete_document",
+    "document_exists",
+    "fetch_graph",
+    "get_driver",
+    "read_document_json",
+    "write_chunks",
+    "write_document",
+]

document-parser/infra/neo4j/chunk_writer.py

@@ -0,0 +1,134 @@
+"""ChunkWriter — push chunk nodes and DERIVED_FROM edges to Neo4j.
+
+Embeddings stay in OpenSearch. Each :Chunk node carries a chunk_index so the
+OpenSearch entry can be retrieved via (doc_id, chunk_index). The
+`embedding_ref` property is reserved for a future vector-store id (not used
+in v0.5 — OpenSearch indexes by doc_id+chunk_index already).
+
+When chunks carry `doc_items` provenance (list of `self_ref` strings), we
+create `(:Chunk)-[:DERIVED_FROM]->(:Element)` links so that queries can go
+from a chunk back to its source elements. Chunks without doc_items get no
+back-links but are still persisted.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from infra.neo4j.driver import Neo4jDriver
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ChunkWriteResult:
+    doc_id: str
+    chunks_written: int
+    derived_from_edges: int
+
+
+def _chunk_id(doc_id: str, index: int) -> str:
+    return f"{doc_id}::chunk::{index}"
+
+
+async def write_chunks(
+    neo: Neo4jDriver,
+    *,
+    doc_id: str,
+    chunks_json: str,
+) -> ChunkWriteResult:
+    """Persist chunks for `doc_id`. Wipes prior chunks first (idempotent)."""
+    chunks: list[dict[str, Any]] = json.loads(chunks_json)
+    active = [c for c in chunks if not c.get("deleted")]
+
+    chunk_rows: list[dict[str, Any]] = []
+    derived_rows: list[dict[str, Any]] = []
+    for idx, c in enumerate(active):
+        cid = _chunk_id(doc_id, idx)
+        chunk_rows.append(
+            {
+                "id": cid,
+                "doc_id": doc_id,
+                "text": c.get("text") or "",
+                "chunk_index": idx,
+                "token_count": c.get("tokenCount") or 0,
+                "embedding_ref": "",
+            }
+        )
+        for item in c.get("docItems") or []:
+            ref = item.get("selfRef") if isinstance(item, dict) else None
+            if ref:
+                derived_rows.append({"chunk_id": cid, "doc_id": doc_id, "self_ref": ref})
+
+    async with (
+        neo.driver.session(database=neo.database) as session,
+        await session.begin_transaction() as tx,
+    ):
+        # Replace existing chunks.
+        await tx.run(
+            """
+                MATCH (d:Document {id: $doc_id})-[:HAS_CHUNK]->(c:Chunk)
+                DETACH DELETE c
+                """,
+            doc_id=doc_id,
+        )
+        await tx.run("MATCH (c:Chunk {doc_id: $doc_id}) DETACH DELETE c", doc_id=doc_id)
+
+        if chunk_rows:
+            await tx.run(
+                """
+                    MATCH (d:Document {id: $doc_id})
+                    UNWIND $rows AS r
+                    CREATE (c:Chunk {
+                      id: r.id,
+                      doc_id: r.doc_id,
+                      text: r.text,
+                      chunk_index: r.chunk_index,
+                      token_count: r.token_count,
+                      embedding_ref: r.embedding_ref
+                    })
+                    MERGE (d)-[:HAS_CHUNK]->(c)
+                    """,
+                doc_id=doc_id,
+                rows=chunk_rows,
+            )
+
+        if derived_rows:
+            await tx.run(
+                """
+                    UNWIND $rows AS r
+                    MATCH (c:Chunk {id: r.chunk_id})
+                    MATCH (e:Element {doc_id: r.doc_id, self_ref: r.self_ref})
+                    MERGE (c)-[:DERIVED_FROM]->(e)
+                    """,
+                rows=derived_rows,
+            )
+
+        # Flag the Document with the new stage.
+        await tx.run(
+            """
+                MATCH (d:Document {id: $doc_id})
+                SET d.stages_applied = [s IN coalesce(d.stages_applied, []) WHERE s <> 'chunks']
+                                       + ['chunks'],
+                    d.last_chunk_write = datetime()
+                """,
+            doc_id=doc_id,
+        )
+
+        await tx.commit()
+
+    logger.info(
+        "Neo4j: wrote %d chunks (%d DERIVED_FROM) for doc %s",
+        len(chunk_rows),
+        len(derived_rows),
+        doc_id,
+    )
+    return ChunkWriteResult(
+        doc_id=doc_id,
+        chunks_written=len(chunk_rows),
+        derived_from_edges=len(derived_rows),
+    )

document-parser/infra/neo4j/driver.py

@@ -0,0 +1,48 @@
+"""Async Neo4j driver wrapper.
+
+Owns a single `AsyncDriver` per process. Callers acquire it via
+`get_driver()` and must call `close_driver()` at shutdown.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from neo4j import AsyncDriver, AsyncGraphDatabase
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Neo4jDriver:
+    driver: AsyncDriver
+    database: str = "neo4j"
+
+
+_instance: Neo4jDriver | None = None
+
+
+async def get_driver(uri: str, user: str, password: str, database: str = "neo4j") -> Neo4jDriver:
+    """Return the process-wide driver, creating it on first call.
+
+    Verifies connectivity once at creation — raises if the server is unreachable.
+    """
+    global _instance
+    if _instance is not None:
+        return _instance
+
+    driver = AsyncGraphDatabase.driver(uri, auth=(user, password))
+    await driver.verify_connectivity()
+    logger.info("Neo4j driver connected to %s (db=%s)", uri, database)
+    _instance = Neo4jDriver(driver=driver, database=database)
+    return _instance
+
+
+async def close_driver() -> None:
+    global _instance
+    if _instance is None:
+        return
+    await _instance.driver.close()
+    _instance = None
+    logger.info("Neo4j driver closed")

document-parser/infra/neo4j/queries.py

@@ -0,0 +1,269 @@
+"""Reusable Cypher queries — kept out of the API layer for reuse + testing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from infra.neo4j.driver import Neo4jDriver
+
+
+@dataclass
+class GraphPayload:
+    doc_id: str
+    nodes: list[dict[str, Any]]
+    edges: list[dict[str, Any]]
+    node_count: int
+    edge_count: int
+    truncated: bool
+    page_count: int
+
+
+# Full graph for one doc: Document + Elements + Pages + Chunks and their edges.
+# Each node/edge type is collected inside its own CALL {} subquery so every
+# block contributes a single row — avoids the cartesian product that chained
+# OPTIONAL MATCH on 6+ edge types would produce (hangs on multi-page docs).
+# See: https://neo4j.com/developer/kb/using-subqueries-to-control-the-scope-of-aggregations/
+#
+# Provenance nodes (post-v0.6 refactor) are NOT returned as top-level graph
+# nodes — they're metadata of their owning Element. We aggregate them inline
+# per element, and derive a dedup'd ON_PAGE edge set from them.
+_FETCH_GRAPH = """
+MATCH (d:Document {id: $doc_id})
+CALL {
+  WITH d
+  MATCH (e:Element {doc_id: d.id})
+  OPTIONAL MATCH (e)-[hp:HAS_PROV]->(pv:Provenance)
+  WITH e, pv ORDER BY hp.order
+  WITH e,
+    collect(
+      CASE WHEN pv IS NULL THEN NULL ELSE {
+        order: pv.prov_order,
+        page_no: pv.page_no,
+        bbox_l: pv.bbox_l, bbox_t: pv.bbox_t,
+        bbox_r: pv.bbox_r, bbox_b: pv.bbox_b,
+        coord_origin: pv.coord_origin,
+        charspan_start: pv.charspan_start,
+        charspan_end: pv.charspan_end
+      } END
+    ) AS all_provs
+  RETURN collect({element: e, provs: [p IN all_provs WHERE p IS NOT NULL]}) AS elements
+}
+CALL { WITH d MATCH (p:Page {doc_id: d.id})    RETURN collect(p) AS pages }
+CALL { WITH d MATCH (c:Chunk {doc_id: d.id})   RETURN collect(c) AS chunks }
+CALL {
+  WITH d
+  MATCH (pe:Element {doc_id: d.id})-[r:PARENT_OF]->(ce:Element)
+  RETURN collect({from: pe.self_ref, to: ce.self_ref, order: r.order, type: 'PARENT_OF'}) AS parent_edges
+}
+CALL {
+  WITH d
+  MATCH (a:Element {doc_id: d.id})-[:NEXT]->(b:Element)
+  RETURN collect({from: a.self_ref, to: b.self_ref, type: 'NEXT'}) AS next_edges
+}
+CALL {
+  WITH d
+  // ON_PAGE is stored on Provenance since v0.6; surface it at the Element
+  // level (dedup'd per Element/Page pair) for the Cytoscape viz.
+  MATCH (er:Element {doc_id: d.id})-[:HAS_PROV]->(:Provenance)-[:ON_PAGE]->(pr:Page)
+  WITH DISTINCT er, pr
+  RETURN collect({from: er.self_ref, to: pr.page_no, type: 'ON_PAGE'}) AS on_page_edges
+}
+CALL {
+  WITH d
+  MATCH (d)-[:HAS_ROOT]->(rr:Element)
+  RETURN collect({from: d.id, to: rr.self_ref, type: 'HAS_ROOT'}) AS has_root_edges
+}
+CALL {
+  WITH d
+  MATCH (d)-[:HAS_CHUNK]->(rc:Chunk)
+  RETURN collect({from: d.id, to: rc.id, type: 'HAS_CHUNK'}) AS has_chunk_edges
+}
+CALL {
+  WITH d
+  MATCH (cc:Chunk {doc_id: d.id})-[:DERIVED_FROM]->(ee:Element)
+  RETURN collect({from: cc.id, to: ee.self_ref, type: 'DERIVED_FROM'}) AS derived_from_edges
+}
+RETURN d AS document, elements, pages, chunks,
+       parent_edges, next_edges, on_page_edges,
+       has_root_edges, has_chunk_edges, derived_from_edges
+"""
+
+
+def _element_node(
+    doc_id: str, e: dict[str, Any], provs: list[dict[str, Any]] | None = None
+) -> dict[str, Any]:
+    # Determine the specific element label: Neo4j returns it via labels(e) on the
+    # driver side; when we project nodes via RETURN, the driver wraps them as Node
+    # objects, so we convert below.
+    first_page: int | None = None
+    if provs:
+        # Convenience: the first provenance's page — the old `prov_page` property,
+        # useful for label rendering in Cytoscape. Full list is in `provs`.
+        first_page = provs[0].get("page_no")
+    return {
+        "id": f"elem::{e.get('self_ref')}",
+        "group": "element",
+        "docling_label": e.get("docling_label"),
+        "self_ref": e.get("self_ref"),
+        "text": (e.get("text") or "")[:200],
+        "prov_page": first_page,
+        "provs": provs or [],
+        "level": e.get("level"),
+        "doc_id": doc_id,
+    }
+
+
+def _page_node(doc_id: str, p: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": f"page::{p.get('page_no')}",
+        "group": "page",
+        "page_no": p.get("page_no"),
+        "width": p.get("width"),
+        "height": p.get("height"),
+        "doc_id": doc_id,
+    }
+
+
+def _chunk_node(p: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": f"chunk::{p.get('id')}",
+        "group": "chunk",
+        "chunk_index": p.get("chunk_index"),
+        "text": (p.get("text") or "")[:200],
+        "token_count": p.get("token_count"),
+    }
+
+
+def _edge_id(from_id: str, to_id: str, edge_type: str) -> str:
+    return f"{edge_type}::{from_id}::{to_id}"
+
+
+async def fetch_graph(
+    neo: Neo4jDriver,
+    doc_id: str,
+    *,
+    max_pages: int = 200,
+) -> GraphPayload | None:
+    """Return the full graph for a document, or None if the document is unknown.
+
+    Enforces the page cap from design §8.4: beyond `max_pages`, returns a
+    `truncated=True` payload with empty node/edge lists so the caller can
+    surface a clean error (HTTP 413) to the UI.
+    """
+    async with neo.driver.session(database=neo.database) as session:
+        page_count_result = await session.run(
+            "MATCH (p:Page {doc_id: $doc_id}) RETURN count(p) AS n",
+            doc_id=doc_id,
+        )
+        pc_record = await page_count_result.single()
+        if pc_record is None:
+            return None
+        page_count = int(pc_record["n"])
+
+        exists_result = await session.run(
+            "MATCH (d:Document {id: $doc_id}) RETURN count(d) AS n",
+            doc_id=doc_id,
+        )
+        exists_record = await exists_result.single()
+        if not exists_record or exists_record["n"] == 0:
+            return None
+
+        if page_count > max_pages:
+            return GraphPayload(
+                doc_id=doc_id,
+                nodes=[],
+                edges=[],
+                node_count=0,
+                edge_count=0,
+                truncated=True,
+                page_count=page_count,
+            )
+
+        result = await session.run(_FETCH_GRAPH, doc_id=doc_id)
+        record = await result.single()
+
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+
+    if record is None:
+        return None
+
+    # Document node.
+    doc_node = record["document"]
+    if doc_node is not None:
+        nodes.append(
+            {
+                "id": f"doc::{doc_id}",
+                "group": "document",
+                "doc_id": doc_id,
+                "title": doc_node.get("title"),
+                "stages_applied": doc_node.get("stages_applied"),
+            }
+        )
+
+    # Element nodes, keeping the specific label (:SectionHeader, etc.).
+    # Each row is a {element, provs} dict from the CALL above; provs is a list
+    # of per-provenance dicts in original order.
+    for row in record["elements"] or []:
+        if row is None:
+            continue
+        e = row.get("element") if isinstance(row, dict) else None
+        if e is None:
+            continue
+        provs = [p for p in (row.get("provs") or []) if p is not None]
+        labels = [label for label in e.labels if label != "Element"]
+        node = _element_node(doc_id, dict(e), provs=provs)
+        node["label"] = labels[0] if labels else "TextElement"
+        nodes.append(node)
+
+    # Pages.
+    for p in record["pages"] or []:
+        if p is None:
+            continue
+        nodes.append(_page_node(doc_id, dict(p)))
+
+    # Chunks.
+    for c in record["chunks"] or []:
+        if c is None:
+            continue
+        nodes.append(_chunk_node(dict(c)))
+
+    # Edges — filter out rows whose from/to is null (OPTIONAL MATCH can yield them).
+    def _push_element_edge(e: dict[str, Any], from_prefix: str, to_prefix: str) -> None:
+        frm, to = e.get("from"), e.get("to")
+        if frm is None or to is None:
+            return
+        edges.append(
+            {
+                "id": _edge_id(f"{from_prefix}{frm}", f"{to_prefix}{to}", e["type"]),
+                "source": f"{from_prefix}{frm}",
+                "target": f"{to_prefix}{to}",
+                "type": e["type"],
+                "order": e.get("order"),
+            }
+        )
+
+    for e in record["parent_edges"] or []:
+        _push_element_edge(e, "elem::", "elem::")
+    for e in record["next_edges"] or []:
+        _push_element_edge(e, "elem::", "elem::")
+    for e in record["on_page_edges"] or []:
+        _push_element_edge(e, "elem::", "page::")
+    for e in record["has_root_edges"] or []:
+        _push_element_edge(e, "doc::", "elem::")
+    for e in record["has_chunk_edges"] or []:
+        _push_element_edge(e, "doc::", "chunk::")
+    for e in record["derived_from_edges"] or []:
+        _push_element_edge(e, "chunk::", "elem::")
+
+    return GraphPayload(
+        doc_id=doc_id,
+        nodes=nodes,
+        edges=edges,
+        node_count=len(nodes),
+        edge_count=len(edges),
+        truncated=False,
+        page_count=page_count,
+    )

document-parser/infra/neo4j/schema.py

@@ -0,0 +1,56 @@
+"""Idempotent Neo4j schema bootstrap.
+
+Runs at backend startup. All statements use `IF NOT EXISTS`, so calling
+this multiple times is safe — it's the contract integration tests rely on.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from infra.neo4j.driver import Neo4jDriver
+
+logger = logging.getLogger(__name__)
+
+
+CONSTRAINTS: tuple[str, ...] = (
+    "CREATE CONSTRAINT document_id IF NOT EXISTS FOR (d:Document) REQUIRE d.id IS UNIQUE",
+    "CREATE CONSTRAINT element_composite IF NOT EXISTS "
+    "FOR (e:Element) REQUIRE (e.doc_id, e.self_ref) IS UNIQUE",
+    "CREATE CONSTRAINT page_composite IF NOT EXISTS "
+    "FOR (p:Page) REQUIRE (p.doc_id, p.page_no) IS UNIQUE",
+    "CREATE CONSTRAINT chunk_id IF NOT EXISTS FOR (c:Chunk) REQUIRE c.id IS UNIQUE",
+)
+
+INDEXES: tuple[str, ...] = (
+    "CREATE INDEX element_doc IF NOT EXISTS FOR (e:Element) ON (e.doc_id)",
+    "CREATE INDEX chunk_doc IF NOT EXISTS FOR (c:Chunk) ON (c.doc_id)",
+    # Reasoning tunnel / bbox-highlight: looking up a Provenance by its owner
+    # element is a hot path (one lookup per visited section). Composite index
+    # avoids a full scan of every Provenance in the DB.
+    "CREATE INDEX provenance_element IF NOT EXISTS "
+    "FOR (pv:Provenance) ON (pv.doc_id, pv.element_ref)",
+    "CREATE INDEX provenance_page IF NOT EXISTS FOR (pv:Provenance) ON (pv.doc_id, pv.page_no)",
+)
+
+FULLTEXT_INDEXES: tuple[str, ...] = (
+    "CREATE FULLTEXT INDEX element_text IF NOT EXISTS FOR (e:Element) ON EACH [e.text]",
+)
+
+
+async def bootstrap_schema(neo: Neo4jDriver) -> None:
+    """Create constraints and indexes required by the graph model.
+
+    Idempotent: safe to call on every startup.
+    """
+    async with neo.driver.session(database=neo.database) as session:
+        for stmt in (*CONSTRAINTS, *INDEXES, *FULLTEXT_INDEXES):
+            await session.run(stmt)
+    logger.info(
+        "Neo4j schema bootstrapped (%d constraints, %d indexes, %d fulltext)",
+        len(CONSTRAINTS),
+        len(INDEXES),
+        len(FULLTEXT_INDEXES),
+    )

document-parser/infra/neo4j/tree_reader.py

@@ -0,0 +1,64 @@
+"""TreeReader — fetch a DoclingDocument back from Neo4j.
+
+v0.5.0 implementation relies on the verbatim `document_json` property stored
+on the Document node by TreeWriter. Reconstruction by walking Element nodes
+is deferred to v0.6 (EnrichmentWriter prerequisite), where we may need to
+rebuild the DoclingDocument after enrichments have been patched on graph
+nodes directly.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from infra.neo4j.driver import Neo4jDriver
+
+logger = logging.getLogger(__name__)
+
+
+async def read_document_json(neo: Neo4jDriver, doc_id: str) -> str | None:
+    """Return the stored DoclingDocument JSON for `doc_id`, or None if absent."""
+    async with neo.driver.session(database=neo.database) as session:
+        result = await session.run(
+            "MATCH (d:Document {id: $doc_id}) RETURN d.document_json AS json",
+            doc_id=doc_id,
+        )
+        record = await result.single()
+    if record is None:
+        return None
+    return record["json"]
+
+
+async def document_exists(neo: Neo4jDriver, doc_id: str) -> bool:
+    async with neo.driver.session(database=neo.database) as session:
+        result = await session.run(
+            "MATCH (d:Document {id: $doc_id}) RETURN count(d) AS n",
+            doc_id=doc_id,
+        )
+        record = await result.single()
+    return bool(record and record["n"] > 0)
+
+
+async def delete_document(neo: Neo4jDriver, doc_id: str) -> int:
+    """Wipe everything related to a doc_id. Returns nodes removed."""
+    async with neo.driver.session(database=neo.database) as session:
+        result = await session.run(
+            """
+            MATCH (d:Document {id: $doc_id})
+            OPTIONAL MATCH (d)-[:HAS_ROOT|HAS_CHUNK*0..]->(n)
+            WITH d, collect(DISTINCT n) AS children
+            DETACH DELETE d
+            WITH children
+            UNWIND children AS c
+            DETACH DELETE c
+            RETURN size(children) + 1 AS removed
+            """,
+            doc_id=doc_id,
+        )
+        record = await result.single()
+        # Also clean up orphan elements and pages tagged with this doc_id.
+        await session.run("MATCH (e:Element {doc_id: $doc_id}) DETACH DELETE e", doc_id=doc_id)
+        await session.run("MATCH (p:Page {doc_id: $doc_id}) DETACH DELETE p", doc_id=doc_id)
+    return int(record["removed"]) if record else 0

document-parser/infra/neo4j/tree_writer.py

@@ -0,0 +1,310 @@
+"""TreeWriter — persist a DoclingDocument as a graph in Neo4j.
+
+v0.5.0 strategy: replace-on-write. For a given doc_id, all existing
+Document/Element/Page/Chunk nodes are wiped before re-ingestion. The full
+serialized `DoclingDocument` JSON is stored as a property on the Document
+node so that `TreeReader` can round-trip it verbatim — reconstruction from
+graph nodes is deferred to v0.6 (see docs/design/neo4j-integration.md §2).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from infra.docling_tree import (
+    build_collapse_index,
+    dfs_order,
+    element_label,
+    is_inline_group,
+    iter_items,
+    iter_pages,
+    iter_provs,
+    parent_ref,
+)
+
+if TYPE_CHECKING:
+    from infra.neo4j.driver import Neo4jDriver
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TreeWriteResult:
+    doc_id: str
+    elements_written: int
+    pages_written: int
+    provenances_written: int = 0
+
+
+def _element_props(item: dict[str, Any], doc_id: str) -> dict[str, Any]:
+    """Properties stored on the `:Element` node itself.
+
+    Provenance (page + bbox) is NOT here anymore — see `_iter_provs` and the
+    `:Provenance` nodes. Keeping it out of the element matches DoclingDocument's
+    own model (`prov` is a list of objects, not a scalar).
+    """
+    props: dict[str, Any] = {
+        "doc_id": doc_id,
+        "self_ref": item.get("self_ref") or "",
+        "docling_label": (item.get("label") or "").lower(),
+        "text": item.get("text") or "",
+    }
+    # Type-specific extras.
+    if "level" in item:
+        props["level"] = item.get("level")
+    if "caption" in item and isinstance(item.get("caption"), str):
+        props["caption"] = item.get("caption")
+    if item.get("data") and isinstance(item["data"], dict):
+        # Tables carry cell layout under data; stringify to keep the schema flat.
+        with contextlib.suppress(TypeError, ValueError):
+            props["cells_json"] = json.dumps(item["data"])
+    return props
+
+
+async def write_document(
+    neo: Neo4jDriver,
+    *,
+    doc_id: str,
+    filename: str,
+    document_json: str,
+    tenant_id: str = "default",
+    source_uri: str | None = None,
+    docling_version: str | None = None,
+) -> TreeWriteResult:
+    """Persist the full DoclingDocument tree to Neo4j.
+
+    Idempotent: wipes any existing graph for doc_id before writing.
+    Fails fast (exception propagates) if Neo4j is unavailable — per design §8.5.
+    """
+    doc_data = json.loads(document_json)
+    ingested_at = datetime.now(tz=UTC).isoformat()
+
+    # Issue #197: collapse two noise patterns from Docling into the projection.
+    # InlineGroups (paragraph style runs) are merged into a single :Paragraph,
+    # and Pictures' internal text labels (flowchart/diagram/chart annotations)
+    # are dropped. Both produce refs that land in `skip_refs`.
+    skip_refs, inline_meta = build_collapse_index(doc_data)
+
+    elements: list[dict[str, Any]] = []
+    # Parallel list: one row per Provenance — each refers back to its owner
+    # element via `self_ref`, so we can batch MATCH-and-link after both node
+    # sets are created.
+    provenances: list[dict[str, Any]] = []
+    for _, item in iter_items(doc_data):
+        ref = item.get("self_ref")
+        if not ref or ref in skip_refs:
+            continue
+        specific = element_label(item.get("label") or "")
+        props = _element_props(item, doc_id)
+        if is_inline_group(item):
+            meta = inline_meta.get(ref, {"text": "", "provs": []})
+            props["text"] = meta["text"]
+            item_provs = meta["provs"]
+        else:
+            item_provs = iter_provs(item)
+        elements.append(
+            {
+                "specific_label": specific,
+                "parent_ref": parent_ref(item),
+                **props,
+            }
+        )
+        for prov in item_provs:
+            provenances.append({"doc_id": doc_id, "self_ref": ref, **prov})
+
+    pages: list[dict[str, Any]] = [{"doc_id": doc_id, **p} for p in iter_pages(doc_data)]
+
+    reading_order = dfs_order(doc_data, skip_refs)
+
+    async with (
+        neo.driver.session(database=neo.database) as session,
+        await session.begin_transaction() as tx,
+    ):
+        # 1. Wipe existing graph for this doc_id (replace strategy).
+        await tx.run(
+            "MATCH (d:Document {id: $doc_id}) "
+            "OPTIONAL MATCH (d)-[:HAS_ROOT|HAS_CHUNK*0..]->(n) "
+            "DETACH DELETE d, n",
+            doc_id=doc_id,
+        )
+        # Orphan sweep — covers Provenance/Element/Page/Chunk that may linger
+        # from an interrupted write or a pre-refactor schema.
+        await tx.run("MATCH (pv:Provenance {doc_id: $doc_id}) DETACH DELETE pv", doc_id=doc_id)
+        await tx.run("MATCH (e:Element {doc_id: $doc_id}) DETACH DELETE e", doc_id=doc_id)
+        await tx.run("MATCH (p:Page {doc_id: $doc_id}) DETACH DELETE p", doc_id=doc_id)
+
+        # 2. Document node (carries the verbatim JSON for TreeReader).
+        await tx.run(
+            """
+                CREATE (d:Document {
+                  id: $doc_id,
+                  title: $title,
+                  source_uri: $source_uri,
+                  ingested_at: datetime($ingested_at),
+                  docling_version: $docling_version,
+                  stages_applied: ['tree'],
+                  last_tree_write: datetime($ingested_at),
+                  tenant_id: $tenant_id,
+                  document_json: $document_json
+                })
+                """,
+            doc_id=doc_id,
+            title=filename,
+            source_uri=source_uri or "",
+            ingested_at=ingested_at,
+            docling_version=docling_version or "",
+            tenant_id=tenant_id,
+            document_json=document_json,
+        )
+
+        # 3. Page nodes.
+        if pages:
+            await tx.run(
+                "UNWIND $pages AS p "
+                "CREATE (:Page {doc_id: p.doc_id, page_no: p.page_no, "
+                "width: p.width, height: p.height})",
+                pages=pages,
+            )
+
+        # 4. Element nodes — use dynamic :Element:<specific> labels via APOC-free trick.
+        # We split by specific label so the CREATE statement is static (no APOC).
+        by_specific: dict[str, list[dict[str, Any]]] = {}
+        for e in elements:
+            by_specific.setdefault(e["specific_label"], []).append(e)
+        for specific, batch in by_specific.items():
+            await tx.run(
+                f"""
+                    UNWIND $batch AS e
+                    CREATE (n:Element:{specific} {{
+                      doc_id: e.doc_id,
+                      self_ref: e.self_ref,
+                      docling_label: e.docling_label,
+                      text: e.text,
+                      level: e.level,
+                      caption: e.caption,
+                      cells_json: e.cells_json
+                    }})
+                    """,
+                batch=batch,
+            )
+
+        # 5. PARENT_OF relations (tree structure). Order tracked inline.
+        parent_rows = [
+            {
+                "doc_id": doc_id,
+                "parent_ref": e["parent_ref"],
+                "child_ref": e["self_ref"],
+                "order": idx,
+            }
+            for idx, e in enumerate(elements)
+            if e["parent_ref"] and e["parent_ref"] != "#/body"
+        ]
+        if parent_rows:
+            await tx.run(
+                """
+                    UNWIND $rows AS r
+                    MATCH (p:Element {doc_id: r.doc_id, self_ref: r.parent_ref})
+                    MATCH (c:Element {doc_id: r.doc_id, self_ref: r.child_ref})
+                    MERGE (p)-[rel:PARENT_OF]->(c)
+                    SET rel.order = r.order
+                    """,
+                rows=parent_rows,
+            )
+
+        # 6. HAS_ROOT for top-level children of the document body.
+        root_rows = [
+            {"doc_id": doc_id, "child_ref": e["self_ref"]}
+            for e in elements
+            if e["parent_ref"] == "#/body"
+        ]
+        if root_rows:
+            await tx.run(
+                """
+                    UNWIND $rows AS r
+                    MATCH (d:Document {id: r.doc_id})
+                    MATCH (c:Element {doc_id: r.doc_id, self_ref: r.child_ref})
+                    MERGE (d)-[:HAS_ROOT]->(c)
+                    """,
+                rows=root_rows,
+            )
+
+        # 7. Provenance nodes — one per (element, prov-entry) pair. Mirrors
+        # Docling's `item.prov = list[ProvenanceItem]` 1:1 so a single item
+        # that spans page breaks (or appears twice in the layout) keeps every
+        # (page, bbox, charspan) without losing data.
+        if provenances:
+            await tx.run(
+                """
+                    UNWIND $rows AS r
+                    MATCH (e:Element {doc_id: r.doc_id, self_ref: r.self_ref})
+                    CREATE (pv:Provenance {
+                      doc_id: r.doc_id,
+                      element_ref: r.self_ref,
+                      prov_order: r.order,
+                      page_no: r.page_no,
+                      bbox_l: r.bbox_l,
+                      bbox_t: r.bbox_t,
+                      bbox_r: r.bbox_r,
+                      bbox_b: r.bbox_b,
+                      coord_origin: r.coord_origin,
+                      charspan_start: r.charspan_start,
+                      charspan_end: r.charspan_end
+                    })
+                    CREATE (e)-[:HAS_PROV {order: r.order}]->(pv)
+                    """,
+                rows=provenances,
+            )
+            # ON_PAGE now attaches the Provenance to its Page — lets downstream
+            # queries ("what's on page 3?") stay simple without walking through
+            # the Element. A Provenance with no page_no (rare) yields no edge.
+            await tx.run(
+                """
+                    UNWIND $rows AS r
+                    WITH r WHERE r.page_no IS NOT NULL
+                    MATCH (pv:Provenance {
+                      doc_id: r.doc_id,
+                      element_ref: r.self_ref,
+                      prov_order: r.order
+                    })
+                    MATCH (p:Page {doc_id: r.doc_id, page_no: r.page_no})
+                    MERGE (pv)-[:ON_PAGE]->(p)
+                    """,
+                rows=provenances,
+            )
+
+        # 8. NEXT chain in DFS pre-order.
+        if len(reading_order) > 1:
+            pairs = [
+                {"doc_id": doc_id, "a": reading_order[i], "b": reading_order[i + 1]}
+                for i in range(len(reading_order) - 1)
+            ]
+            await tx.run(
+                """
+                    UNWIND $pairs AS p
+                    MATCH (a:Element {doc_id: p.doc_id, self_ref: p.a})
+                    MATCH (b:Element {doc_id: p.doc_id, self_ref: p.b})
+                    MERGE (a)-[:NEXT]->(b)
+                    """,
+                pairs=pairs,
+            )
+
+        await tx.commit()
+
+    logger.info(
+        "Neo4j: wrote doc %s (%d elements, %d pages, %d provenances)",
+        doc_id,
+        len(elements),
+        len(pages),
+        len(provenances),
+    )
+    return TreeWriteResult(
+        doc_id=doc_id,
+        elements_written=len(elements),
+        pages_written=len(pages),
+        provenances_written=len(provenances),
+    )

document-parser/infra/opensearch_store.py

@@ -0,0 +1,215 @@
+"""OpenSearch adapter implementing the VectorStore port.
+
+Uses the opensearch-py client for kNN vector search, full-text search,
+and document CRUD against an OpenSearch cluster.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from opensearchpy import AsyncOpenSearch, NotFoundError
+
+from domain.vector_schema import (
+    ChunkBboxEntry,
+    ChunkOrigin,
+    DocItemRef,
+    IndexedChunk,
+    SearchResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _hit_to_indexed_chunk(hit: dict[str, Any]) -> IndexedChunk:
+    """Reconstruct an IndexedChunk from an OpenSearch _source document."""
+    src = hit["_source"]
+    origin_raw = src.get("origin")
+    origin = (
+        ChunkOrigin(binary_hash=origin_raw["binary_hash"], filename=origin_raw["filename"])
+        if origin_raw
+        else None
+    )
+    return IndexedChunk(
+        doc_id=src["doc_id"],
+        filename=src["filename"],
+        content=src["content"],
+        embedding=src.get("embedding", []),
+        chunk_index=src["chunk_index"],
+        chunk_type=src["chunk_type"],
+        page_number=src["page_number"],
+        bboxes=[
+            ChunkBboxEntry(page=b["page"], x=b["x"], y=b["y"], w=b["w"], h=b["h"])
+            for b in src.get("bboxes", [])
+        ],
+        headings=src.get("headings", []),
+        doc_items=[
+            DocItemRef(self_ref=d["self_ref"], label=d["label"]) for d in src.get("doc_items", [])
+        ],
+        origin=origin,
+    )
+
+
+def _hit_to_result(hit: dict[str, Any]) -> SearchResult:
+    """Convert an OpenSearch hit to a SearchResult."""
+    return SearchResult(
+        chunk=_hit_to_indexed_chunk(hit),
+        score=hit.get("_score", 0.0),
+    )
+
+
+class OpenSearchStore:
+    """Concrete VectorStore adapter backed by OpenSearch.
+
+    Satisfies the ``VectorStore`` Protocol defined in ``domain.ports``.
+
+    Args:
+        url: OpenSearch cluster URL (e.g. ``http://localhost:9200``).
+        verify_certs: Whether to verify TLS certificates.
+    """
+
+    def __init__(self, url: str, *, verify_certs: bool = False, default_limit: int = 1000) -> None:
+        self._client = AsyncOpenSearch(
+            hosts=[url],
+            use_ssl=url.startswith("https"),
+            verify_certs=verify_certs,
+            ssl_show_warn=False,
+        )
+        self._default_limit = default_limit
+
+    # -- lifecycle -------------------------------------------------------------
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._client.close()
+
+    async def ping(self) -> bool:
+        """Reachability probe — calls OpenSearch `/` (cluster info) once."""
+        try:
+            info = await self._client.info()
+            return bool(info)
+        except Exception:
+            return False
+
+    # -- VectorStore protocol methods ------------------------------------------
+
+    async def ensure_index(self, index_name: str, mapping: dict) -> None:
+        """Create the index if it does not exist. No-op if it already exists."""
+        exists = await self._client.indices.exists(index=index_name)
+        if not exists:
+            await self._client.indices.create(index=index_name, body=mapping)
+            logger.info("Created OpenSearch index '%s'", index_name)
+        else:
+            logger.debug("Index '%s' already exists — skipping creation", index_name)
+
+    async def index_chunks(self, index_name: str, chunks: list[IndexedChunk]) -> int:
+        """Bulk-index a list of chunks. Returns the number successfully indexed."""
+        if not chunks:
+            return 0
+
+        body: list[dict[str, Any]] = []
+        for chunk in chunks:
+            doc_id = f"{chunk.doc_id}_{chunk.chunk_index}"
+            body.append({"index": {"_index": index_name, "_id": doc_id}})
+            body.append(chunk.to_dict())
+
+        resp = await self._client.bulk(body=body, refresh="wait_for")
+
+        errors = sum(1 for item in resp["items"] if item["index"].get("error"))
+        indexed = len(chunks) - errors
+        if errors:
+            logger.warning("Bulk index to '%s': %d/%d failed", index_name, errors, len(chunks))
+        return indexed
+
+    async def search_similar(
+        self,
+        index_name: str,
+        embedding: list[float],
+        *,
+        k: int = 10,
+        doc_id: str | None = None,
+    ) -> list[SearchResult]:
+        """kNN search for the k nearest chunks by embedding similarity."""
+        knn_query: dict[str, Any] = {
+            "knn": {
+                "embedding": {
+                    "vector": embedding,
+                    "k": k,
+                },
+            },
+        }
+        if doc_id:
+            knn_query["knn"]["embedding"]["filter"] = {
+                "term": {"doc_id": doc_id},
+            }
+
+        resp = await self._client.search(
+            index=index_name,
+            body={"size": k, "query": knn_query},
+            _source_excludes=["embedding"],
+        )
+        return [_hit_to_result(hit) for hit in resp["hits"]["hits"]]
+
+    async def get_chunks(
+        self,
+        index_name: str,
+        doc_id: str,
+        *,
+        limit: int | None = None,
+    ) -> list[SearchResult]:
+        """Retrieve all indexed chunks for a document, ordered by chunk_index."""
+        if limit is None:
+            limit = self._default_limit
+        resp = await self._client.search(
+            index=index_name,
+            body={
+                "size": limit,
+                "query": {"term": {"doc_id": doc_id}},
+                "sort": [{"chunk_index": {"order": "asc"}}],
+            },
+            _source_excludes=["embedding"],
+        )
+        return [_hit_to_result(hit) for hit in resp["hits"]["hits"]]
+
+    async def delete_document(self, index_name: str, doc_id: str) -> int:
+        """Delete all chunks for a document. Returns the number deleted."""
+        try:
+            resp = await self._client.delete_by_query(
+                index=index_name,
+                body={"query": {"term": {"doc_id": doc_id}}},
+                refresh=True,
+            )
+            deleted: int = resp.get("deleted", 0)
+            return deleted
+        except NotFoundError:
+            return 0
+
+    # -- full-text search (bonus from spec) ------------------------------------
+
+    async def search_fulltext(
+        self,
+        index_name: str,
+        query_text: str,
+        *,
+        k: int = 10,
+        doc_id: str | None = None,
+    ) -> list[SearchResult]:
+        """Full-text search on the content field.
+
+        This method is not part of the VectorStore protocol but is specified
+        in the issue acceptance criteria.
+        """
+        must: list[dict[str, Any]] = [{"match": {"content": query_text}}]
+        if doc_id:
+            must.append({"term": {"doc_id": doc_id}})
+
+        resp = await self._client.search(
+            index=index_name,
+            body={
+                "size": k,
+                "query": {"bool": {"must": must}},
+            },
+            _source_excludes=["embedding"],
+        )
+        return [_hit_to_result(hit) for hit in resp["hits"]["hits"]]

document-parser/infra/serve_converter.py

@@ -21,6 +21,8 @@ import httpx
 from docling_core.types.doc.base import BoundingBox, CoordOrigin
 
 from domain.value_objects import (
+    DEFAULT_PAGE_HEIGHT,
+    DEFAULT_PAGE_WIDTH,
     ConversionOptions,
     ConversionResult,
     PageDetail,
@@ -31,7 +33,6 @@ from infra.bbox import to_topleft_list
 logger = logging.getLogger(__name__)
 
 _API_PREFIX = "/v1"
-_DEFAULT_TIMEOUT = 600.0
 
 # Docling Serve label → our element type
 _LABEL_MAP = {
@@ -56,11 +57,16 @@ _LABEL_MAP = {
 class ServeConverter:
     """Adapter that delegates document conversion to a remote Docling Serve instance."""
 
+    # Docling Serve handles batching server-side; slicing into page batches
+    # client-side would just multiply HTTP roundtrips for no benefit, so
+    # the orchestrator passes the full document through in a single call.
+    supports_page_batching: bool = False
+
     def __init__(
         self,
         base_url: str,
         api_key: str | None = None,
-        timeout: float = _DEFAULT_TIMEOUT,
+        timeout: float = 600.0,
     ):
         self._base_url = base_url.rstrip("/")
         self._api_key = api_key
@@ -95,6 +101,13 @@ class ServeConverter:
                     headers=self._headers(),
                 )
 
+        if response.status_code >= 400:
+            logger.error(
+                "Docling Serve error %d: %s (form_data=%s)",
+                response.status_code,
+                response.text[:500],
+                {k: v for k, v in form_data.items()},
+            )
         response.raise_for_status()
         result_data = response.json()
 
@@ -121,8 +134,12 @@ def _build_form_data(
 ) -> dict[str, str | list[str]]:
     """Build form fields matching Docling Serve's multipart form contract.
 
-    Array fields (to_formats) are sent as lists — httpx encodes them as
+    Serve uses FastAPI's ``Form()`` parsing — list/tuple fields are sent
-    repeated form keys (to_formats=md&to_formats=html&to_formats=json).
+    as **repeated form keys** (httpx encodes Python lists this way
+    automatically: ``to_formats=md&to_formats=html&to_formats=json``).
+
+    Note: ``generate_page_images`` is a PdfPipelineOptions field, NOT a
+    ConvertDocumentsOptions field — sending it causes a 422.
     """
     data: dict[str, str | list[str]] = {
         "to_formats": ["md", "html", "json"],
@@ -134,11 +151,12 @@ def _build_form_data(
         "do_picture_classification": str(options.do_picture_classification).lower(),
         "do_picture_description": str(options.do_picture_description).lower(),
         "include_images": str(options.generate_picture_images).lower(),
-        "generate_page_images": str(options.generate_page_images).lower(),
         "images_scale": str(options.images_scale),
     }
     if page_range is not None:
-        data["page_range"] = f"{page_range[0]}-{page_range[1]}"
+        # Serve expects page_range as two repeated form fields:
+        # page_range=1&page_range=10
+        data["page_range"] = [str(page_range[0]), str(page_range[1])]
     return data
 
 
@@ -192,8 +210,8 @@ def _extract_pages_from_docling_document(doc: dict) -> list[PageDetail]:
         size = page_data.get("size", {})
         pages_dict[page_no] = PageDetail(
             page_number=page_no,
-            width=size.get("width", 612.0),
+            width=size.get("width", DEFAULT_PAGE_WIDTH),
-            height=size.get("height", 792.0),
+            height=size.get("height", DEFAULT_PAGE_HEIGHT),
         )
 
     # Process all element arrays
@@ -220,8 +238,8 @@ def _add_element(item: dict, pages: dict[int, PageDetail]) -> None:
         if page_no not in pages:
             pages[page_no] = PageDetail(
                 page_number=page_no,
-                width=612.0,
+                width=DEFAULT_PAGE_WIDTH,
-                height=792.0,
+                height=DEFAULT_PAGE_HEIGHT,
             )
 
         bbox_data = prov.get("bbox", {})

document-parser/infra/settings.py

@@ -23,8 +23,35 @@ class Settings:
     max_file_size_mb: int = 50  # upload limit in MB (0 = unlimited)
     rate_limit_rpm: int = 100  # requests per minute per IP (0 = disabled)
     batch_page_size: int = 0  # 0 = disabled, > 0 = pages per batch
+    opensearch_url: str = ""  # empty = disabled
+    embedding_url: str = ""  # empty = disabled (e.g. http://localhost:8001)
+    neo4j_uri: str = ""  # empty = disabled (e.g. bolt://neo4j:7687)
+    neo4j_user: str = "neo4j"
+    # DEV DEFAULT — the dev compose stack uses "changeme" so `docker compose
+    # up` works out of the box. The backend logs a loud warning at boot if
+    # Neo4j is wired (NEO4J_URI set) AND the password is still the default,
+    # so prod operators notice if they inherited it by accident. Real
+    # deployments must override NEO4J_PASSWORD.
+    neo4j_password: str = "changeme"
+    # Live reasoning via docling-agent — off by default (heavy deps, needs an
+    # Ollama host reachable from the backend). Toggle REASONING_ENABLED=true +
+    # point OLLAMA_HOST at a running instance (default http://localhost:11434).
+    reasoning_enabled: bool = False
+    # LLM backend the reasoning runner talks to. Today only "ollama" is
+    # realizable (docling-agent is hardwired to Ollama via mellea); kept as a
+    # config knob to make the LLMProvider abstraction visible and prepare the
+    # ground for additional backends.
+    llm_provider_type: str = "ollama"
+    ollama_host: str = "http://localhost:11434"
+    reasoning_model_id: str = "gpt-oss:20b"  # matches docling-agent's example_05
+    opensearch_default_limit: int = 1000  # max chunks returned by get_chunks
+    embedding_dimension: int = 384  # Granite Embedding 30M / all-MiniLM-L6-v2
     upload_dir: str = "./uploads"
     db_path: str = "./data/docling_studio.db"
+    max_paste_image_size_mb: int = 10  # clipboard-paste image limit in MB (0 = unlimited)
+    paste_allowed_image_types: list[str] = field(
+        default_factory=lambda: ["image/png", "image/jpeg", "image/webp"]
+    )
     cors_origins: list[str] = field(
         default_factory=lambda: ["http://localhost:3000", "http://localhost:5173"]
     )
@@ -47,10 +74,22 @@ class Settings:
             errors.append(f"max_file_size must be >= 0 (got {self.max_file_size})")
         if self.max_file_size_mb < 0:
             errors.append(f"max_file_size_mb must be >= 0 (got {self.max_file_size_mb})")
+        if self.max_paste_image_size_mb < 0:
+            errors.append(
+                f"max_paste_image_size_mb must be >= 0 (got {self.max_paste_image_size_mb})"
+            )
+        if not self.paste_allowed_image_types:
+            errors.append("paste_allowed_image_types must not be empty")
         if self.rate_limit_rpm < 0:
             errors.append(f"rate_limit_rpm must be >= 0 (got {self.rate_limit_rpm})")
         if self.batch_page_size < 0:
             errors.append(f"batch_page_size must be >= 0 (got {self.batch_page_size})")
+        if self.opensearch_default_limit < 1:
+            errors.append(
+                f"opensearch_default_limit must be >= 1 (got {self.opensearch_default_limit})"
+            )
+        if self.embedding_dimension < 1:
+            errors.append(f"embedding_dimension must be >= 1 (got {self.embedding_dimension})")
         if self.default_table_mode not in ("accurate", "fast"):
             errors.append(
                 f"default_table_mode must be 'accurate' or 'fast' (got '{self.default_table_mode}')"
@@ -74,6 +113,9 @@ class Settings:
     def from_env(cls) -> Settings:
         """Build a Settings instance from environment variables."""
         cors_raw = os.environ.get("CORS_ORIGINS", "http://localhost:3000,http://localhost:5173")
+        paste_types_raw = os.environ.get(
+            "PASTE_ALLOWED_IMAGE_TYPES", "image/png,image/jpeg,image/webp"
+        )
         return cls(
             app_version=os.environ.get("APP_VERSION", "dev"),
             conversion_engine=os.environ.get("CONVERSION_ENGINE", "local"),
@@ -89,9 +131,27 @@ class Settings:
             max_file_size=int(os.environ.get("MAX_FILE_SIZE", "0")),
             max_file_size_mb=int(os.environ.get("MAX_FILE_SIZE_MB", "50")),
             rate_limit_rpm=int(os.environ.get("RATE_LIMIT_RPM", "100")),
+            # 0 = batching disabled (matches dataclass default). Batching
+            # preserves memory on very large docs but `merge_results` drops
+            # `document_json`, which breaks the reasoning tunnel. Enable
+            # explicitly (e.g. 50+) for memory-bound deploys.
             batch_page_size=int(os.environ.get("BATCH_PAGE_SIZE", "0")),
+            opensearch_url=os.environ.get("OPENSEARCH_URL", ""),
+            embedding_url=os.environ.get("EMBEDDING_URL", ""),
+            neo4j_uri=os.environ.get("NEO4J_URI", ""),
+            neo4j_user=os.environ.get("NEO4J_USER", "neo4j"),
+            neo4j_password=os.environ.get("NEO4J_PASSWORD", "changeme"),
+            reasoning_enabled=os.environ.get("REASONING_ENABLED", "false").lower()
+            in ("1", "true", "yes", "on"),
+            llm_provider_type=os.environ.get("LLM_PROVIDER_TYPE", "ollama"),
+            ollama_host=os.environ.get("OLLAMA_HOST", "http://localhost:11434"),
+            reasoning_model_id=os.environ.get("REASONING_MODEL_ID", "gpt-oss:20b"),
+            opensearch_default_limit=int(os.environ.get("OPENSEARCH_DEFAULT_LIMIT", "1000")),
+            embedding_dimension=int(os.environ.get("EMBEDDING_DIMENSION", "384")),
             upload_dir=os.environ.get("UPLOAD_DIR", "./uploads"),
             db_path=os.environ.get("DB_PATH", "./data/docling_studio.db"),
+            max_paste_image_size_mb=int(os.environ.get("MAX_PASTE_IMAGE_SIZE_MB", "10")),
+            paste_allowed_image_types=[t.strip() for t in paste_types_raw.split(",") if t.strip()],
             cors_origins=[o.strip() for o in cors_raw.split(",")],
         )
 

document-parser/main.py

@@ -20,6 +20,7 @@ from fastapi.middleware.cors import CORSMiddleware
 
 from api.analyses import router as analyses_router
 from api.documents import router as documents_router
+from api.ingestion import router as ingestion_router
 from api.schemas import HealthResponse
 from infra.rate_limiter import RateLimiterMiddleware
 from infra.settings import settings
@@ -28,6 +29,7 @@ from persistence.database import get_connection, init_db
 from persistence.document_repo import SqliteDocumentRepository
 from services.analysis_service import AnalysisConfig, AnalysisService
 from services.document_service import DocumentConfig, DocumentService
+from services.ingestion_service import IngestionConfig, IngestionService
 
 logging.basicConfig(
     level=logging.INFO,
@@ -45,6 +47,7 @@ def _build_converter():
         return ServeConverter(
             base_url=settings.docling_serve_url,
             api_key=settings.docling_serve_api_key,
+            timeout=settings.conversion_timeout,
         )
     else:
         from infra.local_converter import LocalConverter
@@ -54,12 +57,15 @@ def _build_converter():
 
 
 def _build_chunker():
-    """Build the chunker adapter — only available in local mode."""
+    """Build the chunker adapter.
-    if settings.conversion_engine == "local":
-        from infra.local_chunker import LocalChunker
 
-        return LocalChunker()
+    Uses LocalChunker in all modes — in remote mode it chunks the
-    return None
+    DoclingDocument JSON returned by Docling Serve, so docling-core
+    (lightweight) is the only local dependency needed.
+    """
+    from infra.local_chunker import LocalChunker
+
+    return LocalChunker()
 
 
 def _build_repos() -> tuple[SqliteDocumentRepository, SqliteAnalysisRepository]:
@@ -69,6 +75,7 @@ def _build_repos() -> tuple[SqliteDocumentRepository, SqliteAnalysisRepository]:
 def _build_analysis_service(
     document_repo: SqliteDocumentRepository,
     analysis_repo: SqliteAnalysisRepository,
+    neo4j_driver=None,
 ) -> AnalysisService:
     converter = _build_converter()
     chunker = _build_chunker()
@@ -84,9 +91,66 @@ def _build_analysis_service(
         conversion_timeout=settings.conversion_timeout,
         max_concurrent=settings.max_concurrent_analyses,
         config=config,
+        neo4j_driver=neo4j_driver,
     )
 
 
+async def _init_neo4j():
+    """Initialize the Neo4j driver and bootstrap schema — skip if not configured."""
+    if not settings.neo4j_uri:
+        logger.info("Neo4j disabled (NEO4J_URI not set)")
+        return None
+
+    if settings.neo4j_password == "changeme":
+        # The dev compose stack ships with "changeme" so `docker compose up`
+        # works immediately. Anyone running the backend against a non-dev
+        # Neo4j with this password almost certainly forgot to override it.
+        logger.warning(
+            "Neo4j is configured with the dev default password 'changeme'. "
+            "Override NEO4J_PASSWORD before deploying outside localhost."
+        )
+
+    from infra.neo4j import bootstrap_schema, get_driver
+
+    try:
+        neo = await get_driver(
+            settings.neo4j_uri,
+            settings.neo4j_user,
+            settings.neo4j_password,
+        )
+        await bootstrap_schema(neo)
+        logger.info("Neo4j ready (uri=%s)", settings.neo4j_uri)
+        return neo
+    except Exception:
+        logger.exception("Neo4j init failed — continuing without graph storage")
+        return None
+
+
+def _build_ingestion_service(neo4j_driver=None) -> IngestionService | None:
+    """Build the ingestion service — only if embedding + opensearch are configured."""
+    if not settings.embedding_url or not settings.opensearch_url:
+        logger.info("Ingestion disabled (EMBEDDING_URL or OPENSEARCH_URL not set)")
+        return None
+
+    from infra.embedding_client import EmbeddingClient
+    from infra.opensearch_store import OpenSearchStore
+
+    embedding = EmbeddingClient(settings.embedding_url)
+    vector_store = OpenSearchStore(
+        settings.opensearch_url,
+        default_limit=settings.opensearch_default_limit,
+    )
+    config = IngestionConfig(
+        embedding_dimension=settings.embedding_dimension,
+    )
+    logger.info(
+        "Ingestion enabled (embedding=%s, opensearch=%s)",
+        settings.embedding_url,
+        settings.opensearch_url,
+    )
+    return IngestionService(embedding, vector_store, config, neo4j_driver=neo4j_driver)
+
+
 def _build_document_service(
     document_repo: SqliteDocumentRepository,
     analysis_repo: SqliteAnalysisRepository,
@@ -112,10 +176,30 @@ def _build_document_service(
 async def lifespan(app: FastAPI) -> AsyncIterator[None]:
     await init_db()
     document_repo, analysis_repo = _build_repos()
-    app.state.analysis_service = _build_analysis_service(document_repo, analysis_repo)
+    # Exposed on app.state so routers that need direct repo access (e.g. the
+    # reasoning-graph endpoint, which reads `document_json` from SQLite to
+    # build the graph without touching Neo4j) can reach them without going
+    # through a service.
+    app.state.analysis_repo = analysis_repo
+    app.state.document_repo = document_repo
+    app.state.neo4j = await _init_neo4j()
+    app.state.analysis_service = _build_analysis_service(
+        document_repo, analysis_repo, neo4j_driver=app.state.neo4j
+    )
     app.state.document_service = _build_document_service(document_repo, analysis_repo)
+    ingestion_service = _build_ingestion_service(neo4j_driver=app.state.neo4j)
+    app.state.ingestion_service = ingestion_service
+    if ingestion_service is not None:
+        app.include_router(ingestion_router)
+        logger.info("Ingestion router mounted")
     logger.info("Docling Studio backend ready (engine=%s)", settings.conversion_engine)
-    yield
+    try:
+        yield
+    finally:
+        if app.state.neo4j is not None:
+            from infra.neo4j import close_driver
+
+            await close_driver()
 
 
 app = FastAPI(
@@ -128,7 +212,7 @@ app.add_middleware(
     CORSMiddleware,
     allow_origins=settings.cors_origins,
     allow_credentials=True,
-    allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+    allow_methods=["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
     allow_headers=["Content-Type", "Authorization"],
 )
 if settings.rate_limit_rpm > 0:
@@ -141,6 +225,54 @@ if settings.rate_limit_rpm > 0:
 app.include_router(documents_router)
 app.include_router(analyses_router)
 
+# Graph view — mounted regardless; individual requests 503 if Neo4j is absent.
+from api.graph import router as graph_router  # noqa: E402
+
+app.include_router(graph_router)
+
+# Live reasoning (docling-agent runner). Router is mounted unconditionally so
+# the route is introspectable in OpenAPI; the handler itself 503s when
+# `REASONING_ENABLED` is off or the deps aren't installed.
+from api.reasoning import router as reasoning_router  # noqa: E402
+from infra.docling_agent_reasoning import DoclingAgentReasoningRunner  # noqa: E402
+from infra.docling_agent_reasoning import deps_present as _reasoning_deps_present  # noqa: E402
+from infra.llm.ollama_provider import OllamaProvider  # noqa: E402
+
+app.include_router(reasoning_router)
+
+
+def _build_reasoning_runner() -> DoclingAgentReasoningRunner | None:
+    """Wire the reasoning runner if `REASONING_ENABLED=true` and deps are
+    importable. Today only `LLM_PROVIDER_TYPE=ollama` is supported (cf.
+    `LLMProvider` docstring); other values fall through to a logged warning
+    + None so the rest of the app boots cleanly.
+    """
+    if not settings.reasoning_enabled:
+        return None
+    if not _reasoning_deps_present():
+        logger.warning(
+            "REASONING_ENABLED=true but docling-agent / mellea not importable — "
+            "reasoning runner disabled"
+        )
+        return None
+    if settings.llm_provider_type != "ollama":
+        logger.warning(
+            "Unsupported LLM_PROVIDER_TYPE=%s — reasoning runner disabled (only "
+            "'ollama' is realizable today, see "
+            "https://github.com/docling-project/docling-agent/issues/26)",
+            settings.llm_provider_type,
+        )
+        return None
+
+    provider = OllamaProvider(
+        host=settings.ollama_host,
+        default_model_id=settings.reasoning_model_id,
+    )
+    return DoclingAgentReasoningRunner(provider=provider)
+
+
+app.state.reasoning_runner = _build_reasoning_runner()
+
 
 @app.get("/api/health", response_model=HealthResponse)
 async def health() -> HealthResponse:
@@ -154,6 +286,7 @@ async def health() -> HealthResponse:
         logger.warning("Health check: database unreachable", exc_info=True)
 
     status = "ok" if db_status == "ok" else "degraded"
+    runner = getattr(app.state, "reasoning_runner", None)
     return HealthResponse(
         status=status,
         version=settings.app_version,
@@ -162,4 +295,13 @@ async def health() -> HealthResponse:
         database=db_status,
         max_page_count=settings.max_page_count if settings.max_page_count > 0 else None,
         max_file_size_mb=settings.max_file_size_mb if settings.max_file_size_mb > 0 else None,
+        max_paste_image_size_mb=(
+            settings.max_paste_image_size_mb if settings.max_paste_image_size_mb > 0 else None
+        ),
+        paste_allowed_image_types=settings.paste_allowed_image_types,
+        ingestion_available=getattr(app.state, "ingestion_service", None) is not None,
+        # True when the runner is wired and reports itself available. The
+        # actual Ollama reachability is checked lazily at call-time to avoid
+        # blocking health checks on the LLM host.
+        reasoning_available=runner is not None and runner.is_available,
     )

document-parser/persistence/analysis_repo.py

@@ -73,6 +73,23 @@ class SqliteAnalysisRepository:
             row = await cursor.fetchone()
             return _row_to_job(row) if row else None
 
+    async def find_latest_completed_by_document(self, document_id: str) -> AnalysisJob | None:
+        """Latest COMPLETED analysis with a non-null `document_json` for a doc.
+
+        Used by the reasoning-trace tunnel to prime Neo4j from an existing
+        analysis when the graph doesn't yet exist (e.g. analysis ran before
+        Neo4j was wired in).
+        """
+        async with get_connection() as db:
+            cursor = await db.execute(
+                f"{_SELECT_WITH_DOC} WHERE aj.document_id = ? "
+                "AND aj.status = 'COMPLETED' AND aj.document_json IS NOT NULL "
+                "ORDER BY aj.completed_at DESC LIMIT 1",
+                (document_id,),
+            )
+            row = await cursor.fetchone()
+            return _row_to_job(row) if row else None
+
     async def update_status(self, job: AnalysisJob) -> None:
         """Persist all mutable fields of an analysis job (status, results, timestamps)."""
         async with get_connection() as db:

document-parser/persistence/database.py

@@ -9,11 +9,9 @@ from contextlib import asynccontextmanager
 
 import aiosqlite
 
-from infra.settings import settings
-
 logger = logging.getLogger(__name__)
 
-DB_PATH = settings.db_path
+DB_PATH = os.environ.get("DB_PATH", "./data/docling_studio.db")
 
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS documents (

document-parser/requirements-test.txt

@@ -0,0 +1,4 @@
+-r requirements.txt
+pytest>=8.0.0,<9.0.0
+pytest-asyncio>=0.23.0,<1.0.0
+pytestarch>=2.0.0,<3.0.0

document-parser/requirements.txt

@@ -1,4 +1,4 @@
-docling-core>=2.0.0,<3.0.0
+docling-core[chunking]>=2.0.0,<3.0.0
 fastapi>=0.115.0,<1.0.0
 uvicorn[standard]>=0.32.0,<1.0.0
 python-multipart>=0.0.12
@@ -7,3 +7,11 @@ pillow>=10.0.0,<11.0.0
 aiosqlite>=0.20.0,<1.0.0
 httpx>=0.27.0,<1.0.0
 pypdfium2>=4.0.0,<5.0.0
+opensearch-py[async]>=2.6.0,<3.0.0
+neo4j>=5.15.0,<6.0.0
+# R&D reasoning-trace live runner — calls docling-agent's `_rag_loop` over
+# an Ollama backend. Gated server-side by `REASONING_ENABLED`; pulls ~60MB
+# of deps. See https://github.com/docling-project/docling-agent/issues/26 for
+# the public-API replacement of `_rag_loop`.
+docling-agent==0.1.0
+mellea==0.4.2

document-parser/services/analysis_service.py

@@ -44,6 +44,7 @@ def _chunk_to_dict(c: ChunkResult) -> dict:
         "sourcePage": c.source_page,
         "tokenCount": c.token_count,
         "bboxes": [{"page": b.page, "bbox": b.bbox} for b in c.bboxes],
+        "docItems": [{"selfRef": d.self_ref, "label": d.label} for d in c.doc_items],
     }
 
 
@@ -69,6 +70,7 @@ class AnalysisConfig:
 
     default_table_mode: str = "accurate"
     batch_page_size: int = 0
+    neo4j_required: bool = False  # if True, ingestion fails when Neo4j write fails
 
 
 class AnalysisService:
@@ -83,6 +85,7 @@ class AnalysisService:
         conversion_timeout: int = 600,
         max_concurrent: int = _DEFAULT_MAX_CONCURRENT,
         config: AnalysisConfig | None = None,
+        neo4j_driver=None,
     ):
         self._converter = converter
         self._chunker = chunker
@@ -93,6 +96,7 @@ class AnalysisService:
         self._running_tasks: dict[str, asyncio.Task] = {}
         self._background_tasks: set[asyncio.Task] = set()
         self._config = config or AnalysisConfig()
+        self._neo4j = neo4j_driver
 
     async def create(
         self,
@@ -160,6 +164,49 @@ class AnalysisService:
 
         return chunks
 
+    async def update_chunk_text(self, job_id: str, chunk_index: int, text: str) -> list[dict]:
+        """Update the text of a single chunk by index. Returns the full updated chunks list."""
+        job = await self._analysis_repo.find_by_id(job_id)
+        if not job:
+            raise ValueError(f"Analysis not found: {job_id}")
+        if job.status != AnalysisStatus.COMPLETED:
+            raise ValueError(f"Analysis is not completed: {job_id}")
+        if not job.chunks_json:
+            raise ValueError(f"No chunks available: {job_id}")
+
+        chunks = json.loads(job.chunks_json)
+        if chunk_index < 0 or chunk_index >= len(chunks):
+            raise ValueError(f"Chunk index out of range: {chunk_index}")
+
+        chunks[chunk_index]["text"] = text
+        chunks[chunk_index]["modified"] = True
+
+        chunks_json = json.dumps(chunks)
+        await self._analysis_repo.update_chunks(job_id, chunks_json)
+
+        return chunks
+
+    async def delete_chunk(self, job_id: str, chunk_index: int) -> list[dict]:
+        """Soft-delete a chunk by index. Returns the full updated chunks list."""
+        job = await self._analysis_repo.find_by_id(job_id)
+        if not job:
+            raise ValueError(f"Analysis not found: {job_id}")
+        if job.status != AnalysisStatus.COMPLETED:
+            raise ValueError(f"Analysis is not completed: {job_id}")
+        if not job.chunks_json:
+            raise ValueError(f"No chunks available: {job_id}")
+
+        chunks = json.loads(job.chunks_json)
+        if chunk_index < 0 or chunk_index >= len(chunks):
+            raise ValueError(f"Chunk index out of range: {chunk_index}")
+
+        chunks[chunk_index]["deleted"] = True
+
+        chunks_json = json.dumps(chunks)
+        await self._analysis_repo.update_chunks(job_id, chunks_json)
+
+        return chunks
+
     async def _run_batched_conversion(
         self,
         job_id: str,
@@ -281,11 +328,16 @@ class AnalysisService:
         file_path: str,
         options: ConversionOptions,
     ) -> ConversionResult | None:
-        """Run batched or single conversion. Returns None if the job was deleted mid-batch."""
+        """Run batched or single conversion. Returns None if the job was deleted mid-batch.
+
+        Batching is only used for local mode — it limits memory usage when
+        Docling runs in-process.  In remote mode the Serve instance manages
+        its own resources, and batching would discard document_json (needed
+        for chunking).
+        """
         total_pages = _count_pdf_pages(file_path)
         batch_size = self._config.batch_page_size
-
+        if batch_size > 0 and total_pages > batch_size and self._converter.supports_page_batching:
-        if batch_size > 0 and total_pages > batch_size:
             return await self._run_batched_conversion(
                 job_id, file_path, options, total_pages, batch_size
             )
@@ -327,8 +379,32 @@ class AnalysisService:
         if result.page_count:
             await self._document_repo.update_page_count(job.document_id, result.page_count)
 
+        await self._write_tree_to_neo4j(job, result.document_json)
+
         logger.info("Analysis completed: %s (%d pages)", job_id, result.page_count)
 
+    async def _write_tree_to_neo4j(self, job, document_json: str | None) -> None:
+        """Mirror the DoclingDocument tree into Neo4j if configured.
+
+        Silent no-op when Neo4j isn't wired in. Logs but does not fail the
+        analysis when the write fails, unless `config.neo4j_required` is set.
+        """
+        if self._neo4j is None or not document_json:
+            return
+        try:
+            from infra.neo4j import write_document
+
+            await write_document(
+                self._neo4j,
+                doc_id=job.document_id,
+                filename=job.document_filename or job.document_id,
+                document_json=document_json,
+            )
+        except Exception:
+            logger.exception("Neo4j TreeWriter failed for doc %s", job.document_id)
+            if self._config.neo4j_required:
+                raise
+
     async def _run_analysis_inner(
         self,
         job_id: str,

document-parser/services/ingestion_service.py

@@ -0,0 +1,200 @@
+"""Ingestion service — orchestrates Docling → embedding → OpenSearch.
+
+Chains the full ingestion pipeline:
+1. Convert document via Docling (reuse existing analysis)
+2. Chunk with selected strategy
+3. Embed all chunk texts via EmbeddingService
+4. Index into OpenSearch via VectorStore
+
+Idempotent: re-ingesting a document deletes old chunks before re-indexing.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from domain.vector_schema import (
+    ChunkBboxEntry,
+    ChunkOrigin,
+    IndexedChunk,
+    build_index_mapping,
+)
+
+if TYPE_CHECKING:
+    from domain.ports import EmbeddingService, VectorStore
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class IngestionConfig:
+    """Configuration for the ingestion pipeline."""
+
+    index_name: str = "docling-studio-chunks"
+    embedding_dimension: int = 384
+
+
+@dataclass
+class IngestionResult:
+    """Result of an ingestion pipeline run."""
+
+    doc_id: str
+    chunks_indexed: int
+    embedding_dimension: int
+
+
+class IngestionService:
+    """Orchestrates the embedding + indexing pipeline."""
+
+    def __init__(
+        self,
+        embedding_service: EmbeddingService,
+        vector_store: VectorStore,
+        config: IngestionConfig | None = None,
+        neo4j_driver=None,
+    ) -> None:
+        self._embedding = embedding_service
+        self._vector_store = vector_store
+        self._config = config or IngestionConfig()
+        self._neo4j = neo4j_driver
+
+    async def ensure_index(self) -> None:
+        """Ensure the vector index exists with the correct mapping."""
+        mapping = build_index_mapping(self._config.embedding_dimension)
+        await self._vector_store.ensure_index(self._config.index_name, mapping)
+
+    async def ingest(
+        self,
+        doc_id: str,
+        filename: str,
+        chunks_json: str,
+        *,
+        binary_hash: str | None = None,
+    ) -> IngestionResult:
+        """Run the embedding + indexing pipeline on pre-chunked data.
+
+        This method is idempotent: it deletes any existing chunks for the
+        document before re-indexing.
+
+        Args:
+            doc_id: Unique document identifier.
+            filename: Original filename.
+            chunks_json: JSON-serialized list of chunk dicts (from analysis).
+            binary_hash: Optional hash of the source file for provenance.
+
+        Returns:
+            IngestionResult with the number of chunks indexed.
+        """
+        await self.ensure_index()
+
+        chunks_data: list[dict] = json.loads(chunks_json)
+        active_chunks = [c for c in chunks_data if not c.get("deleted")]
+        if not active_chunks:
+            logger.info("No active chunks for doc %s — skipping ingestion", doc_id)
+            return IngestionResult(doc_id=doc_id, chunks_indexed=0, embedding_dimension=0)
+
+        # 1. Embed all chunk texts
+        texts = [c["text"] for c in active_chunks]
+        logger.info("Embedding %d chunks for doc %s", len(texts), doc_id)
+        embeddings = await self._embedding.embed(texts)
+
+        # 2. Build IndexedChunk domain objects
+        origin = (
+            ChunkOrigin(binary_hash=binary_hash or "", filename=filename) if binary_hash else None
+        )
+        indexed_chunks: list[IndexedChunk] = []
+        for i, (chunk_data, embedding) in enumerate(zip(active_chunks, embeddings, strict=True)):
+            bboxes = [
+                ChunkBboxEntry(
+                    page=b["page"],
+                    x=b["bbox"][0] if b.get("bbox") else 0,
+                    y=b["bbox"][1] if b.get("bbox") else 0,
+                    w=(b["bbox"][2] - b["bbox"][0]) if b.get("bbox") and len(b["bbox"]) >= 4 else 0,
+                    h=(b["bbox"][3] - b["bbox"][1]) if b.get("bbox") and len(b["bbox"]) >= 4 else 0,
+                )
+                for b in chunk_data.get("bboxes", [])
+            ]
+            indexed_chunks.append(
+                IndexedChunk(
+                    doc_id=doc_id,
+                    filename=filename,
+                    content=chunk_data["text"],
+                    embedding=embedding,
+                    chunk_index=i,
+                    chunk_type=chunk_data.get("chunkType", "text"),
+                    page_number=chunk_data.get("sourcePage", 0) or 0,
+                    bboxes=bboxes,
+                    headings=chunk_data.get("headings", []),
+                    origin=origin,
+                )
+            )
+
+        # 3. Delete old chunks (idempotent re-indexing)
+        deleted = await self._vector_store.delete_document(self._config.index_name, doc_id)
+        if deleted:
+            logger.info("Deleted %d old chunks for doc %s", deleted, doc_id)
+
+        # 4. Index new chunks
+        indexed = await self._vector_store.index_chunks(self._config.index_name, indexed_chunks)
+        logger.info("Indexed %d/%d chunks for doc %s", indexed, len(indexed_chunks), doc_id)
+
+        # 5. Mirror chunks in Neo4j if configured (with DERIVED_FROM edges).
+        if self._neo4j is not None:
+            try:
+                from infra.neo4j import write_chunks
+
+                await write_chunks(self._neo4j, doc_id=doc_id, chunks_json=chunks_json)
+            except Exception:
+                logger.exception("Neo4j ChunkWriter failed for doc %s", doc_id)
+
+        return IngestionResult(
+            doc_id=doc_id,
+            chunks_indexed=indexed,
+            embedding_dimension=len(embeddings[0]) if embeddings else 0,
+        )
+
+    async def delete_document(self, doc_id: str) -> int:
+        """Remove all indexed chunks for a document."""
+        return await self._vector_store.delete_document(self._config.index_name, doc_id)
+
+    async def search(
+        self,
+        query: str,
+        *,
+        k: int = 10,
+        doc_id: str | None = None,
+    ) -> list:
+        """Semantic search: embed the query then find nearest chunks."""
+        embeddings = await self._embedding.embed([query])
+        return await self._vector_store.search_similar(
+            self._config.index_name,
+            embeddings[0],
+            k=k,
+            doc_id=doc_id,
+        )
+
+    async def search_fulltext(
+        self,
+        query: str,
+        *,
+        k: int = 20,
+        doc_id: str | None = None,
+    ) -> list:
+        """Full-text keyword search in indexed chunks."""
+        return await self._vector_store.search_fulltext(
+            self._config.index_name,
+            query,
+            k=k,
+            doc_id=doc_id,
+        )
+
+    async def ping(self) -> bool:
+        """Check if the underlying vector store is reachable."""
+        try:
+            return await self._vector_store.ping()
+        except Exception:
+            logger.debug("Vector store ping failed", exc_info=True)
+            return False

document-parser/tests/neo4j/conftest.py

@@ -0,0 +1,40 @@
+"""Shared fixtures for Neo4j integration tests.
+
+These tests are skipped unless a live Neo4j is reachable via NEO4J_TEST_URI
+(defaulting to bolt://localhost:7687). CI spins up `neo4j:5.15-community`
+alongside the job; locally run `docker compose -f docker-compose.dev.yml up neo4j`.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+# Skip the entire module cleanly when the neo4j driver package is absent
+# (e.g. local dev without the dependency installed).
+pytest.importorskip("neo4j")
+
+from infra.neo4j import close_driver, get_driver
+
+
+def _cfg() -> tuple[str, str, str]:
+    return (
+        os.environ.get("NEO4J_TEST_URI", "bolt://localhost:7687"),
+        os.environ.get("NEO4J_TEST_USER", "neo4j"),
+        os.environ.get("NEO4J_TEST_PASSWORD", "changeme"),
+    )
+
+
+@pytest.fixture
+async def neo4j_driver():
+    uri, user, password = _cfg()
+    try:
+        neo = await get_driver(uri, user, password)
+    except Exception as exc:
+        pytest.skip(f"Neo4j not reachable at {uri}: {exc}")
+    # Wipe DB before each test — integration tests assume an empty graph.
+    async with neo.driver.session(database=neo.database) as session:
+        await session.run("MATCH (n) DETACH DELETE n")
+    yield neo
+    await close_driver()

document-parser/tests/neo4j/test_chunk_writer.py

@@ -0,0 +1,113 @@
+"""ChunkWriter creates Chunk nodes + DERIVED_FROM links.
+
+Builds on the tree_writer fixture — writes the tree first so that DERIVED_FROM
+has Elements to link against.
+"""
+
+from __future__ import annotations
+
+import json
+
+from infra.neo4j import fetch_graph, write_chunks, write_document
+from infra.neo4j.schema import bootstrap_schema
+from tests.neo4j.test_tree_writer import FIXTURE
+
+CHUNKS = [
+    {
+        "text": "Introduction. First paragraph on page 1.",
+        "sourcePage": 1,
+        "tokenCount": 8,
+        "docItems": [
+            {"selfRef": "#/texts/0", "label": "section_header"},
+            {"selfRef": "#/texts/1", "label": "paragraph"},
+        ],
+    },
+    {
+        "text": "Continued on page 2.",
+        "sourcePage": 2,
+        "tokenCount": 4,
+        "docItems": [{"selfRef": "#/texts/2", "label": "paragraph"}],
+        "deleted": False,
+    },
+    # soft-deleted chunk: must be ignored
+    {"text": "gone", "deleted": True, "docItems": []},
+]
+
+
+async def test_write_chunks_and_derived_from(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    await write_document(
+        neo4j_driver,
+        doc_id="doc-fixture",
+        filename="fixture.pdf",
+        document_json=json.dumps(FIXTURE),
+    )
+
+    result = await write_chunks(
+        neo4j_driver,
+        doc_id="doc-fixture",
+        chunks_json=json.dumps(CHUNKS),
+    )
+
+    assert result.chunks_written == 2
+    assert result.derived_from_edges == 3
+
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as s:
+        count = await (
+            await s.run(
+                "MATCH (:Document {id: $id})-[:HAS_CHUNK]->(c:Chunk) RETURN count(c) AS n",
+                id="doc-fixture",
+            )
+        ).single()
+        assert count["n"] == 2
+
+        # First chunk derives from 2 elements, second from 1.
+        for idx, expected in [(0, 2), (1, 1)]:
+            cnt = await (
+                await s.run(
+                    "MATCH (c:Chunk {id: $cid})-[:DERIVED_FROM]->(e:Element) RETURN count(e) AS n",
+                    cid=f"doc-fixture::chunk::{idx}",
+                )
+            ).single()
+            assert cnt["n"] == expected
+
+        stages = await (
+            await s.run(
+                "MATCH (d:Document {id: $id}) RETURN d.stages_applied AS s", id="doc-fixture"
+            )
+        ).single()
+        assert "chunks" in stages["s"]
+
+
+async def test_fetch_graph_returns_full_payload(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    await write_document(
+        neo4j_driver,
+        doc_id="doc-fixture",
+        filename="fixture.pdf",
+        document_json=json.dumps(FIXTURE),
+    )
+    await write_chunks(
+        neo4j_driver,
+        doc_id="doc-fixture",
+        chunks_json=json.dumps(CHUNKS),
+    )
+
+    payload = await fetch_graph(neo4j_driver, "doc-fixture")
+    assert payload is not None
+    assert payload.truncated is False
+    assert payload.page_count == 2
+
+    groups = {n["group"] for n in payload.nodes}
+    assert groups == {"document", "element", "page", "chunk"}
+
+    edge_types = {e["type"] for e in payload.edges}
+    # Every edge kind this fixture can produce should be present.
+    # PARENT_OF is intentionally excluded: all FIXTURE items have
+    # `parent = #/body`, so they're roots (→ HAS_ROOT) with no nested hierarchy.
+    assert {"HAS_ROOT", "NEXT", "ON_PAGE", "HAS_CHUNK", "DERIVED_FROM"} <= edge_types
+
+
+async def test_fetch_graph_missing_doc_returns_none(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    assert await fetch_graph(neo4j_driver, "no-such-doc") is None

document-parser/tests/neo4j/test_document_roundtrip.py

@@ -0,0 +1,32 @@
+"""Minimal Document node round-trip — validates the driver + schema end-to-end."""
+
+from __future__ import annotations
+
+from infra.neo4j.schema import bootstrap_schema
+
+
+async def test_document_write_read_delete(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as session:
+        await session.run(
+            "CREATE (d:Document {id: $id, title: $title, tenant_id: $tenant})",
+            id="doc-42",
+            title="Round-trip fixture",
+            tenant="default",
+        )
+
+        result = await session.run(
+            "MATCH (d:Document {id: $id}) RETURN d.title AS title, d.tenant_id AS tenant",
+            id="doc-42",
+        )
+        record = await result.single()
+        assert record is not None
+        assert record["title"] == "Round-trip fixture"
+        assert record["tenant"] == "default"
+
+        await session.run("MATCH (d:Document {id: $id}) DETACH DELETE d", id="doc-42")
+        gone = await (
+            await session.run("MATCH (d:Document {id: $id}) RETURN d", id="doc-42")
+        ).single()
+        assert gone is None

document-parser/tests/neo4j/test_driver.py

@@ -0,0 +1,10 @@
+"""Neo4j driver connectivity smoke test."""
+
+from __future__ import annotations
+
+
+async def test_driver_connects_and_runs_cypher(neo4j_driver):
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as session:
+        result = await session.run("RETURN 1 AS x")
+        record = await result.single()
+        assert record["x"] == 1

document-parser/tests/neo4j/test_schema.py

@@ -0,0 +1,38 @@
+"""Schema bootstrap is idempotent and produces the expected constraints/indexes."""
+
+from __future__ import annotations
+
+from infra.neo4j.schema import CONSTRAINTS, FULLTEXT_INDEXES, INDEXES, bootstrap_schema
+
+
+async def _count_schema(neo4j_driver) -> tuple[int, int]:
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as session:
+        constraints = await (await session.run("SHOW CONSTRAINTS")).data()
+        indexes = await (await session.run("SHOW INDEXES")).data()
+    return len(constraints), len(indexes)
+
+
+async def test_bootstrap_is_idempotent(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    first = await _count_schema(neo4j_driver)
+
+    # Running a second time must not duplicate anything.
+    await bootstrap_schema(neo4j_driver)
+    second = await _count_schema(neo4j_driver)
+
+    assert first == second
+    # Sanity: we created at least what we declared.
+    assert first[0] >= len(CONSTRAINTS)
+    assert first[1] >= len(INDEXES) + len(FULLTEXT_INDEXES)
+
+
+async def test_document_id_is_unique(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as session:
+        await session.run("CREATE (d:Document {id: 'doc-1', title: 'first'})")
+        with_err: Exception | None = None
+        try:
+            await session.run("CREATE (d:Document {id: 'doc-1', title: 'dup'})")
+        except Exception as exc:
+            with_err = exc
+        assert with_err is not None, "unique constraint on Document.id must reject duplicates"

document-parser/tests/neo4j/test_tree_writer.py

@@ -0,0 +1,469 @@
+"""TreeWriter round-trip + structural sanity checks.
+
+Fixture is a hand-crafted DoclingDocument JSON with: one section containing
+two paragraphs and a table, spanning two pages. Tests verify that the graph
+mirrors the structure (HAS_ROOT, PARENT_OF, ON_PAGE, NEXT) and that
+re-writing the same doc is an idempotent replace.
+"""
+
+from __future__ import annotations
+
+import json
+
+from infra.neo4j import read_document_json, write_document
+from infra.neo4j.schema import bootstrap_schema
+
+FIXTURE = {
+    "name": "fixture.pdf",
+    "pages": {
+        "1": {"page_no": 1, "size": {"width": 595, "height": 842}},
+        "2": {"page_no": 2, "size": {"width": 595, "height": 842}},
+    },
+    "body": {
+        "self_ref": "#/body",
+        "children": [
+            {"$ref": "#/texts/0"},
+            {"$ref": "#/texts/1"},
+            {"$ref": "#/texts/2"},
+            {"$ref": "#/tables/0"},
+        ],
+    },
+    "texts": [
+        {
+            "self_ref": "#/texts/0",
+            "parent": {"$ref": "#/body"},
+            "label": "section_header",
+            "text": "Introduction",
+            "level": 1,
+            "prov": [{"page_no": 1, "bbox": {"l": 10, "t": 10, "r": 100, "b": 30}}],
+        },
+        {
+            "self_ref": "#/texts/1",
+            "parent": {"$ref": "#/body"},
+            "label": "paragraph",
+            "text": "First paragraph on page 1.",
+            "prov": [{"page_no": 1, "bbox": {"l": 10, "t": 40, "r": 500, "b": 80}}],
+        },
+        {
+            "self_ref": "#/texts/2",
+            "parent": {"$ref": "#/body"},
+            "label": "paragraph",
+            "text": "Continued on page 2.",
+            "prov": [{"page_no": 2, "bbox": {"l": 10, "t": 40, "r": 500, "b": 80}}],
+        },
+    ],
+    "tables": [
+        {
+            "self_ref": "#/tables/0",
+            "parent": {"$ref": "#/body"},
+            "label": "table",
+            "text": "",
+            "data": {"num_rows": 2, "num_cols": 2, "grid": [[1, 2], [3, 4]]},
+            "prov": [{"page_no": 2, "bbox": {"l": 10, "t": 90, "r": 500, "b": 200}}],
+        }
+    ],
+    "pictures": [],
+    "groups": [],
+}
+
+
+async def _count(session, cypher: str, **params) -> int:
+    r = await session.run(cypher, **params)
+    rec = await r.single()
+    return int(rec["n"]) if rec else 0
+
+
+async def test_write_creates_expected_structure(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    doc_json = json.dumps(FIXTURE)
+
+    result = await write_document(
+        neo4j_driver,
+        doc_id="doc-fixture",
+        filename="fixture.pdf",
+        document_json=doc_json,
+    )
+
+    assert result.elements_written == 4
+    assert result.pages_written == 2
+    # Every item in FIXTURE has exactly one prov entry → 4 Provenance nodes.
+    assert result.provenances_written == 4
+
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as s:
+        assert (
+            await _count(
+                s,
+                "MATCH (d:Document {id: $id}) RETURN count(d) AS n",
+                id="doc-fixture",
+            )
+            == 1
+        )
+        assert (
+            await _count(
+                s,
+                "MATCH (:Document {id: $id})-[:HAS_ROOT]->(e:Element) RETURN count(e) AS n",
+                id="doc-fixture",
+            )
+            == 4
+        )
+        assert (
+            await _count(
+                s,
+                "MATCH (e:Element:SectionHeader {doc_id: $id, self_ref: '#/texts/0'}) "
+                "RETURN count(e) AS n",
+                id="doc-fixture",
+            )
+            == 1
+        )
+        assert (
+            await _count(
+                s,
+                "MATCH (e:Element:Table {doc_id: $id}) RETURN count(e) AS n",
+                id="doc-fixture",
+            )
+            == 1
+        )
+        # Reading-order chain: 3 NEXT edges for 4 elements.
+        assert (
+            await _count(
+                s,
+                "MATCH (a:Element {doc_id: $id})-[:NEXT]->(b:Element {doc_id: $id}) "
+                "RETURN count(*) AS n",
+                id="doc-fixture",
+            )
+            == 3
+        )
+        # Post-v0.6: ON_PAGE attaches Provenance to Page, not Element directly.
+        # Traverse through the Provenance node.
+        assert (
+            await _count(
+                s,
+                "MATCH (:Element {doc_id: $id})-[:HAS_PROV]->"
+                "(:Provenance)-[:ON_PAGE]->(:Page {doc_id: $id}) "
+                "RETURN count(*) AS n",
+                id="doc-fixture",
+            )
+            == 4
+        )
+        # Each element has exactly one Provenance here (single-page fixture).
+        assert (
+            await _count(
+                s,
+                "MATCH (e:Element {doc_id: $id})-[:HAS_PROV]->(pv:Provenance) "
+                "RETURN count(pv) AS n",
+                id="doc-fixture",
+            )
+            == 4
+        )
+
+
+async def test_rewrite_is_idempotent_replace(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    doc_json = json.dumps(FIXTURE)
+
+    await write_document(
+        neo4j_driver,
+        doc_id="doc-fixture",
+        filename="fixture.pdf",
+        document_json=doc_json,
+    )
+    # Second write with the same id must not duplicate anything.
+    await write_document(
+        neo4j_driver,
+        doc_id="doc-fixture",
+        filename="fixture.pdf",
+        document_json=doc_json,
+    )
+
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as s:
+        assert (
+            await _count(s, "MATCH (d:Document {id: $id}) RETURN count(d) AS n", id="doc-fixture")
+            == 1
+        )
+        assert (
+            await _count(
+                s,
+                "MATCH (e:Element {doc_id: $id}) RETURN count(e) AS n",
+                id="doc-fixture",
+            )
+            == 4
+        )
+
+
+async def test_reader_returns_verbatim_json(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    doc_json = json.dumps(FIXTURE, sort_keys=True)
+    await write_document(
+        neo4j_driver,
+        doc_id="doc-fixture",
+        filename="fixture.pdf",
+        document_json=doc_json,
+    )
+
+    read_back = await read_document_json(neo4j_driver, "doc-fixture")
+    assert read_back is not None
+    assert json.loads(read_back) == json.loads(doc_json)
+
+
+async def test_reader_missing_doc_returns_none(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    assert await read_document_json(neo4j_driver, "no-such-doc") is None
+
+
+# Issue #197: Docling emits one InlineGroup per inline-styled paragraph plus N
+# child `text` items (one per style run). Naive 1:1 mirroring blew up section
+# graphs into per-style-run nodes. The writer now collapses an InlineGroup into
+# a single :Paragraph node carrying the concatenated text of its children, and
+# skips those children entirely.
+INLINE_FIXTURE = {
+    "name": "inline.html",
+    "pages": {
+        "1": {"page_no": 1, "size": {"width": 595, "height": 842}},
+    },
+    "body": {
+        "self_ref": "#/body",
+        "children": [
+            {"$ref": "#/texts/0"},
+            {"$ref": "#/groups/0"},
+        ],
+    },
+    "texts": [
+        {
+            "self_ref": "#/texts/0",
+            "parent": {"$ref": "#/body"},
+            "label": "section_header",
+            "text": "Heading",
+            "level": 1,
+            "prov": [{"page_no": 1, "bbox": {"l": 10, "t": 10, "r": 100, "b": 30}}],
+        },
+        {
+            "self_ref": "#/texts/1",
+            "parent": {"$ref": "#/groups/0"},
+            "label": "text",
+            "text": "Hello",
+            "prov": [{"page_no": 1, "bbox": {"l": 10, "t": 40, "r": 50, "b": 60}}],
+        },
+        {
+            "self_ref": "#/texts/2",
+            "parent": {"$ref": "#/groups/0"},
+            "label": "text",
+            "text": "world",
+            "prov": [{"page_no": 1, "bbox": {"l": 55, "t": 40, "r": 100, "b": 60}}],
+        },
+        {
+            "self_ref": "#/texts/3",
+            "parent": {"$ref": "#/groups/0"},
+            "label": "text",
+            "text": "!",
+            "prov": [{"page_no": 1, "bbox": {"l": 105, "t": 40, "r": 110, "b": 60}}],
+        },
+    ],
+    "tables": [],
+    "pictures": [],
+    "groups": [
+        {
+            "self_ref": "#/groups/0",
+            "parent": {"$ref": "#/body"},
+            "label": "inline",
+            "children": [
+                {"$ref": "#/texts/1"},
+                {"$ref": "#/texts/2"},
+                {"$ref": "#/texts/3"},
+            ],
+        },
+    ],
+}
+
+
+async def test_inline_group_collapses_into_single_paragraph(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    doc_json = json.dumps(INLINE_FIXTURE)
+
+    result = await write_document(
+        neo4j_driver,
+        doc_id="doc-inline",
+        filename="inline.html",
+        document_json=doc_json,
+    )
+
+    # Section header + collapsed inline group only — NOT 5 (+3 style runs).
+    assert result.elements_written == 2
+    # The inline group inherits its 3 children's provs (1 each); the section
+    # header has its own prov → 4 Provenance nodes total.
+    assert result.provenances_written == 4
+
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as s:
+        r = await s.run(
+            "MATCH (e:Element:Paragraph {doc_id: $id, self_ref: '#/groups/0'}) "
+            "RETURN e.text AS text",
+            id="doc-inline",
+        )
+        rec = await r.single()
+        assert rec is not None, "InlineGroup should write a :Paragraph node"
+        assert rec["text"] == "Hello world !"
+
+        for child_ref in ("#/texts/1", "#/texts/2", "#/texts/3"):
+            assert (
+                await _count(
+                    s,
+                    "MATCH (e:Element {doc_id: $id, self_ref: $ref}) RETURN count(e) AS n",
+                    id="doc-inline",
+                    ref=child_ref,
+                )
+                == 0
+            ), f"Style-run {child_ref} should be skipped, not written as a node"
+
+        # Inline group inherits provs from all children (order preserved).
+        assert (
+            await _count(
+                s,
+                "MATCH (e:Element:Paragraph {doc_id: $id, self_ref: '#/groups/0'})"
+                "-[:HAS_PROV]->(pv:Provenance) RETURN count(pv) AS n",
+                id="doc-inline",
+            )
+            == 3
+        )
+
+        # Reading order: section_header → inline-as-paragraph (1 NEXT edge).
+        assert (
+            await _count(
+                s,
+                "MATCH (a:Element {doc_id: $id})-[:NEXT]->(b:Element) RETURN count(*) AS n",
+                id="doc-inline",
+            )
+            == 1
+        )
+
+        assert (
+            await _count(
+                s,
+                "MATCH (:Document {id: $id})-[:HAS_ROOT]->(:Element) RETURN count(*) AS n",
+                id="doc-inline",
+            )
+            == 2
+        )
+
+        # ON_PAGE through Provenance → Page (matches the new schema).
+        assert (
+            await _count(
+                s,
+                "MATCH (:Element {doc_id: $id})-[:HAS_PROV]->"
+                "(:Provenance)-[:ON_PAGE]->(:Page) RETURN count(*) AS n",
+                id="doc-inline",
+            )
+            == 4
+        )
+
+
+# Same issue (#197): a Picture's `children` are internal text labels (flowchart
+# boxes, chart axis labels, diagram callouts) extracted by Docling's layout
+# model. Mirroring them 1:1 drowns the figure in dozens of tiny nodes.
+PICTURE_FIXTURE = {
+    "name": "figure.pdf",
+    "pages": {
+        "1": {"page_no": 1, "size": {"width": 595, "height": 842}},
+    },
+    "body": {
+        "self_ref": "#/body",
+        "children": [
+            {"$ref": "#/texts/0"},
+            {"$ref": "#/pictures/0"},
+        ],
+    },
+    "texts": [
+        {
+            "self_ref": "#/texts/0",
+            "parent": {"$ref": "#/body"},
+            "label": "caption",
+            "text": "Figure 1: Pipeline overview.",
+            "prov": [{"page_no": 1, "bbox": {"l": 0, "t": 700, "r": 500, "b": 720}}],
+        },
+        # Internal labels — children of #/pictures/0.
+        {
+            "self_ref": "#/texts/1",
+            "parent": {"$ref": "#/pictures/0"},
+            "label": "text",
+            "text": "Parse",
+            "prov": [{"page_no": 1, "bbox": {"l": 100, "t": 200, "r": 130, "b": 220}}],
+        },
+        {
+            "self_ref": "#/texts/2",
+            "parent": {"$ref": "#/pictures/0"},
+            "label": "text",
+            "text": "Build",
+            "prov": [{"page_no": 1, "bbox": {"l": 140, "t": 200, "r": 170, "b": 220}}],
+        },
+        {
+            "self_ref": "#/texts/3",
+            "parent": {"$ref": "#/pictures/0"},
+            "label": "text",
+            "text": "Enrich",
+            "prov": [{"page_no": 1, "bbox": {"l": 180, "t": 200, "r": 220, "b": 220}}],
+        },
+    ],
+    "tables": [],
+    "pictures": [
+        {
+            "self_ref": "#/pictures/0",
+            "parent": {"$ref": "#/body"},
+            "label": "picture",
+            "children": [
+                {"$ref": "#/texts/1"},
+                {"$ref": "#/texts/2"},
+                {"$ref": "#/texts/3"},
+            ],
+            "captions": [{"$ref": "#/texts/0"}],
+            "prov": [{"page_no": 1, "bbox": {"l": 90, "t": 100, "r": 510, "b": 600}}],
+        }
+    ],
+    "groups": [],
+}
+
+
+async def test_picture_internal_labels_are_skipped(neo4j_driver):
+    await bootstrap_schema(neo4j_driver)
+    doc_json = json.dumps(PICTURE_FIXTURE)
+
+    result = await write_document(
+        neo4j_driver,
+        doc_id="doc-pic",
+        filename="figure.pdf",
+        document_json=doc_json,
+    )
+
+    # Caption + picture only — the 3 internal labels are skipped.
+    assert result.elements_written == 2
+
+    async with neo4j_driver.driver.session(database=neo4j_driver.database) as s:
+        for child_ref in ("#/texts/1", "#/texts/2", "#/texts/3"):
+            assert (
+                await _count(
+                    s,
+                    "MATCH (e:Element {doc_id: $id, self_ref: $ref}) RETURN count(e) AS n",
+                    id="doc-pic",
+                    ref=child_ref,
+                )
+                == 0
+            ), f"Picture child {child_ref} should be skipped"
+
+        # Picture stays a :Figure node with its own prov.
+        assert (
+            await _count(
+                s,
+                "MATCH (e:Element:Figure {doc_id: $id, self_ref: '#/pictures/0'}) "
+                "RETURN count(e) AS n",
+                id="doc-pic",
+            )
+            == 1
+        )
+
+        # No PARENT_OF from the picture to its dropped children.
+        assert (
+            await _count(
+                s,
+                "MATCH (:Element {doc_id: $id, self_ref: '#/pictures/0'})-[:PARENT_OF]->"
+                "(:Element) RETURN count(*) AS n",
+                id="doc-pic",
+            )
+            == 0
+        )

document-parser/tests/test_analysis_service.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 import asyncio
 import functools
+import json
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
+from domain.models import AnalysisStatus
 from domain.services import extract_html_body, merge_results
 from domain.value_objects import ConversionResult, PageDetail
 from services.analysis_service import AnalysisConfig, AnalysisService, _count_pdf_pages
@@ -515,3 +517,141 @@ class TestBatchedConversion:
         assert result is None
         # Only first batch should have been converted
         assert converter.convert.call_count == 1
+
+
+class TestUpdateChunkText:
+    """Tests for AnalysisService.update_chunk_text."""
+
+    @pytest.mark.asyncio
+    async def test_update_chunk_text_success(self):
+        chunks = [
+            {"text": "original", "headings": [], "sourcePage": 1, "tokenCount": 5, "bboxes": []},
+            {"text": "second", "headings": [], "sourcePage": 2, "tokenCount": 3, "bboxes": []},
+        ]
+        job = MagicMock()
+        job.status = AnalysisStatus.COMPLETED
+        job.chunks_json = json.dumps(chunks)
+
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=job)
+        repo.update_chunks = AsyncMock(return_value=True)
+
+        service = _make_service(analysis_repo=repo)
+        result = await service.update_chunk_text("j1", 0, "updated text")
+
+        assert result[0]["text"] == "updated text"
+        assert result[0]["modified"] is True
+        assert result[1]["text"] == "second"
+        assert result[1].get("modified", False) is False
+        repo.update_chunks.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_update_chunk_text_not_found(self):
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=None)
+        service = _make_service(analysis_repo=repo)
+
+        with pytest.raises(ValueError, match="Analysis not found"):
+            await service.update_chunk_text("missing", 0, "text")
+
+    @pytest.mark.asyncio
+    async def test_update_chunk_text_not_completed(self):
+        job = MagicMock()
+        job.status = AnalysisStatus.RUNNING
+
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=job)
+        service = _make_service(analysis_repo=repo)
+
+        with pytest.raises(ValueError, match="not completed"):
+            await service.update_chunk_text("j1", 0, "text")
+
+    @pytest.mark.asyncio
+    async def test_update_chunk_text_index_out_of_range(self):
+        chunks = [
+            {"text": "only one", "headings": [], "sourcePage": 1, "tokenCount": 5, "bboxes": []}
+        ]
+        job = MagicMock()
+        job.status = AnalysisStatus.COMPLETED
+        job.chunks_json = json.dumps(chunks)
+
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=job)
+        service = _make_service(analysis_repo=repo)
+
+        with pytest.raises(ValueError, match="out of range"):
+            await service.update_chunk_text("j1", 5, "text")
+
+    @pytest.mark.asyncio
+    async def test_update_chunk_text_no_chunks(self):
+        job = MagicMock()
+        job.status = AnalysisStatus.COMPLETED
+        job.chunks_json = None
+
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=job)
+        service = _make_service(analysis_repo=repo)
+
+        with pytest.raises(ValueError, match="No chunks available"):
+            await service.update_chunk_text("j1", 0, "text")
+
+
+class TestDeleteChunk:
+    """Tests for AnalysisService.delete_chunk."""
+
+    @pytest.mark.asyncio
+    async def test_delete_chunk_success(self):
+        chunks = [
+            {"text": "chunk1", "headings": [], "sourcePage": 1, "tokenCount": 5, "bboxes": []},
+            {"text": "chunk2", "headings": [], "sourcePage": 2, "tokenCount": 3, "bboxes": []},
+        ]
+        job = MagicMock()
+        job.status = AnalysisStatus.COMPLETED
+        job.chunks_json = json.dumps(chunks)
+
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=job)
+        repo.update_chunks = AsyncMock(return_value=True)
+
+        service = _make_service(analysis_repo=repo)
+        result = await service.delete_chunk("j1", 0)
+
+        assert result[0]["deleted"] is True
+        assert result[1].get("deleted", False) is False
+        repo.update_chunks.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_delete_chunk_not_found(self):
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=None)
+        service = _make_service(analysis_repo=repo)
+
+        with pytest.raises(ValueError, match="Analysis not found"):
+            await service.delete_chunk("missing", 0)
+
+    @pytest.mark.asyncio
+    async def test_delete_chunk_index_out_of_range(self):
+        chunks = [{"text": "only", "headings": [], "sourcePage": 1, "tokenCount": 5, "bboxes": []}]
+        job = MagicMock()
+        job.status = AnalysisStatus.COMPLETED
+        job.chunks_json = json.dumps(chunks)
+
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=job)
+        service = _make_service(analysis_repo=repo)
+
+        with pytest.raises(ValueError, match="out of range"):
+            await service.delete_chunk("j1", 5)
+
+    @pytest.mark.asyncio
+    async def test_delete_chunk_no_chunks(self):
+        job = MagicMock()
+        job.status = AnalysisStatus.COMPLETED
+        job.chunks_json = None
+
+        repo = MagicMock()
+        repo.find_by_id = AsyncMock(return_value=job)
+        service = _make_service(analysis_repo=repo)
+
+        with pytest.raises(ValueError, match="No chunks available"):
+            await service.delete_chunk("j1", 0)

document-parser/tests/test_api_endpoints.py

@@ -51,6 +51,23 @@ class TestHealthEndpoint:
         assert "maxFileSizeMb" in data
         assert data["maxFileSizeMb"] == 50
 
+    def test_health_exposes_ingestion_available_false(self, client):
+        original = getattr(app.state, "ingestion_service", None)
+        app.state.ingestion_service = None
+        resp = client.get("/api/health")
+        app.state.ingestion_service = original
+        data = resp.json()
+        assert "ingestionAvailable" in data
+        assert data["ingestionAvailable"] is False
+
+    def test_health_exposes_ingestion_available_true(self, client):
+        original = getattr(app.state, "ingestion_service", None)
+        app.state.ingestion_service = MagicMock()
+        resp = client.get("/api/health")
+        app.state.ingestion_service = original
+        data = resp.json()
+        assert data["ingestionAvailable"] is True
+
 
 class TestDocumentEndpoints:
     def test_list_documents(self, client, mock_document_service):
@@ -179,7 +196,9 @@ class TestAnalysisEndpoints:
         assert resp.status_code == 200
         data = resp.json()
         assert data["status"] == "RUNNING"
-        assert data["startedAt"] is not None
+        # ISO-8601 datetime string from `mark_running()`
+        assert isinstance(data["startedAt"], str)
+        assert data["startedAt"]  # not empty
 
     def test_get_analysis_not_found(self, client, mock_analysis_service):
         mock_analysis_service.find_by_id = AsyncMock(return_value=None)

document-parser/tests/test_architecture.py

@@ -0,0 +1,208 @@
+"""Hexagonal architecture tests — enforce layer dependency rules.
+
+Uses pytestarch for inter-layer dependency rules and ast-based import
+scanning for external (third-party) dependency constraints.
+
+Rules enforced:
+- domain   -> no import from api, services, infra, persistence
+- services -> no import from api, infra, persistence
+- api      -> no import from infra, persistence
+- infra    -> no import from api, services
+- persistence -> no import from api, services, infra
+- domain   -> no import of fastapi, sqlalchemy, httpx, opensearchpy
+- services -> no import of fastapi
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import pytest
+from pytestarch import Rule, get_evaluable_architecture
+
+# ---------------------------------------------------------------------------
+# pytestarch evaluable (project root = document-parser/)
+# ---------------------------------------------------------------------------
+
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# pytestarch uses the directory name as module prefix when given absolute paths.
+# We use the directory name to build qualified module references.
+_PREFIX = _PROJECT_ROOT.name  # "document-parser"
+
+_evaluable = get_evaluable_architecture(str(_PROJECT_ROOT), str(_PROJECT_ROOT))
+
+
+def _mod(layer: str) -> str:
+    """Return the fully-qualified pytestarch module name for a layer."""
+    return f"{_PREFIX}.{layer}"
+
+
+# ---------------------------------------------------------------------------
+# Helper: collect top-level imports from all .py files in a package
+# ---------------------------------------------------------------------------
+
+
+def _collect_imports(package: str) -> set[str]:
+    """Return the set of top-level module names imported by *package*."""
+    pkg_path = Path(_PROJECT_ROOT) / package
+    imports: set[str] = set()
+    for py_file in pkg_path.rglob("*.py"):
+        tree = ast.parse(py_file.read_text(), filename=str(py_file))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.add(alias.name.split(".")[0])
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                imports.add(node.module.split(".")[0])
+    return imports
+
+
+# ---------------------------------------------------------------------------
+# Inter-layer dependency rules (pytestarch)
+# ---------------------------------------------------------------------------
+
+
+class TestDomainLayerIsolation:
+    """domain must not depend on any other layer."""
+
+    @pytest.mark.parametrize("forbidden", ["api", "services", "infra", "persistence"])
+    def test_domain_does_not_import(self, forbidden: str):
+        rule = (
+            Rule()
+            .modules_that()
+            .are_sub_modules_of(_mod("domain"))
+            .should_not()
+            .import_modules_that()
+            .are_sub_modules_of(_mod(forbidden))
+        )
+        rule.assert_applies(_evaluable)
+
+
+class TestServicesLayerIsolation:
+    """services may import domain only."""
+
+    @pytest.mark.parametrize("forbidden", ["api", "infra", "persistence"])
+    def test_services_does_not_import(self, forbidden: str):
+        rule = (
+            Rule()
+            .modules_that()
+            .are_sub_modules_of(_mod("services"))
+            .should_not()
+            .import_modules_that()
+            .are_sub_modules_of(_mod(forbidden))
+        )
+        rule.assert_applies(_evaluable)
+
+
+class TestApiLayerIsolation:
+    """api may import services and domain, but not infra or persistence."""
+
+    @pytest.mark.parametrize("forbidden", ["infra", "persistence"])
+    def test_api_does_not_import(self, forbidden: str):
+        rule = (
+            Rule()
+            .modules_that()
+            .are_sub_modules_of(_mod("api"))
+            .should_not()
+            .import_modules_that()
+            .are_sub_modules_of(_mod(forbidden))
+        )
+        rule.assert_applies(_evaluable)
+
+
+class TestInfraLayerIsolation:
+    """infra may import domain (ports), but not api or services."""
+
+    @pytest.mark.parametrize("forbidden", ["api", "services"])
+    def test_infra_does_not_import(self, forbidden: str):
+        rule = (
+            Rule()
+            .modules_that()
+            .are_sub_modules_of(_mod("infra"))
+            .should_not()
+            .import_modules_that()
+            .are_sub_modules_of(_mod(forbidden))
+        )
+        rule.assert_applies(_evaluable)
+
+
+class TestPersistenceLayerIsolation:
+    """persistence may import domain, but not api, services, or infra."""
+
+    @pytest.mark.parametrize("forbidden", ["api", "services", "infra"])
+    def test_persistence_does_not_import(self, forbidden: str):
+        rule = (
+            Rule()
+            .modules_that()
+            .are_sub_modules_of(_mod("persistence"))
+            .should_not()
+            .import_modules_that()
+            .are_sub_modules_of(_mod(forbidden))
+        )
+        rule.assert_applies(_evaluable)
+
+
+# ---------------------------------------------------------------------------
+# External dependency rules (ast-based)
+# ---------------------------------------------------------------------------
+
+_DOMAIN_FORBIDDEN_EXTERNALS = {"fastapi", "sqlalchemy", "httpx", "opensearchpy"}
+_SERVICES_FORBIDDEN_EXTERNALS = {"fastapi"}
+
+
+class TestDomainExternalDependencies:
+    """domain must not import infrastructure-specific third-party libraries."""
+
+    @pytest.mark.parametrize("lib", sorted(_DOMAIN_FORBIDDEN_EXTERNALS))
+    def test_domain_does_not_import_external(self, lib: str):
+        imports = _collect_imports("domain")
+        assert lib not in imports, f"domain imports forbidden external library '{lib}'"
+
+
+class TestServicesExternalDependencies:
+    """services must not import web-framework libraries."""
+
+    @pytest.mark.parametrize("lib", sorted(_SERVICES_FORBIDDEN_EXTERNALS))
+    def test_services_does_not_import_external(self, lib: str):
+        imports = _collect_imports("services")
+        assert lib not in imports, f"services imports forbidden external library '{lib}'"
+
+
+# ---------------------------------------------------------------------------
+# Convention: ports live exclusively in domain.ports
+# ---------------------------------------------------------------------------
+
+
+class TestPortConvention:
+    """Protocol definitions (ports) must live in domain.ports only."""
+
+    def test_no_protocol_outside_domain_ports(self):
+        """No Protocol subclass should be defined outside domain/ports.py."""
+        ports_file = Path(_PROJECT_ROOT) / "domain" / "ports.py"
+        for py_file in Path(_PROJECT_ROOT).rglob("*.py"):
+            if py_file == ports_file:
+                continue
+            # Skip test files and __pycache__
+            if "tests" in py_file.parts or "__pycache__" in py_file.parts:
+                continue
+            tree = ast.parse(py_file.read_text(), filename=str(py_file))
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef):
+                    for base in node.bases:
+                        base_name = _get_name(base)
+                        if base_name == "Protocol":
+                            pytest.fail(
+                                f"Protocol '{node.name}' defined in {py_file.relative_to(_PROJECT_ROOT)}"
+                                f" — ports must live in domain/ports.py"
+                            )
+
+
+def _get_name(node: ast.expr) -> str:
+    """Extract a simple name from an AST expression node."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return ""

document-parser/tests/test_chunking.py

@@ -66,6 +66,7 @@ class TestChunkResult:
             "source_page": 1,
             "token_count": 10,
             "bboxes": [],
+            "doc_items": [],
         }
 
 
@@ -278,6 +279,114 @@ class TestCreateAnalysisWithChunking:
         assert chunks[0]["text"] == "chunk1"
 
 
+class TestUpdateChunkTextEndpoint:
+    def test_update_chunk_text_success(self, client, mock_analysis_service):
+        updated_chunks = [
+            {
+                "text": "updated text",
+                "headings": ["H1"],
+                "sourcePage": 1,
+                "tokenCount": 10,
+                "bboxes": [],
+                "modified": True,
+            },
+            {
+                "text": "chunk2",
+                "headings": [],
+                "sourcePage": 2,
+                "tokenCount": 20,
+                "bboxes": [],
+                "modified": False,
+            },
+        ]
+        mock_analysis_service.update_chunk_text = AsyncMock(return_value=updated_chunks)
+
+        resp = client.patch(
+            "/api/analyses/j1/chunks/0",
+            json={"text": "updated text"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert len(data) == 2
+        assert data[0]["text"] == "updated text"
+        assert data[0]["modified"] is True
+        assert data[1]["modified"] is False
+
+    def test_update_chunk_text_invalid_index(self, client, mock_analysis_service):
+        mock_analysis_service.update_chunk_text = AsyncMock(
+            side_effect=ValueError("Chunk index out of range: 99"),
+        )
+        resp = client.patch(
+            "/api/analyses/j1/chunks/99",
+            json={"text": "new"},
+        )
+        assert resp.status_code == 400
+
+    def test_update_chunk_text_not_completed(self, client, mock_analysis_service):
+        mock_analysis_service.update_chunk_text = AsyncMock(
+            side_effect=ValueError("Analysis is not completed: j1"),
+        )
+        resp = client.patch(
+            "/api/analyses/j1/chunks/0",
+            json={"text": "new"},
+        )
+        assert resp.status_code == 400
+
+    def test_update_chunk_text_not_found(self, client, mock_analysis_service):
+        mock_analysis_service.update_chunk_text = AsyncMock(
+            side_effect=ValueError("Analysis not found: j1"),
+        )
+        resp = client.patch(
+            "/api/analyses/j1/chunks/0",
+            json={"text": "new"},
+        )
+        assert resp.status_code == 400
+
+
+class TestDeleteChunkEndpoint:
+    def test_delete_chunk_success(self, client, mock_analysis_service):
+        updated_chunks = [
+            {
+                "text": "chunk1",
+                "headings": [],
+                "sourcePage": 1,
+                "tokenCount": 10,
+                "bboxes": [],
+                "deleted": True,
+            },
+            {
+                "text": "chunk2",
+                "headings": [],
+                "sourcePage": 2,
+                "tokenCount": 20,
+                "bboxes": [],
+                "deleted": False,
+            },
+        ]
+        mock_analysis_service.delete_chunk = AsyncMock(return_value=updated_chunks)
+
+        resp = client.delete("/api/analyses/j1/chunks/0")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert len(data) == 2
+        assert data[0]["deleted"] is True
+        assert data[1]["deleted"] is False
+
+    def test_delete_chunk_invalid_index(self, client, mock_analysis_service):
+        mock_analysis_service.delete_chunk = AsyncMock(
+            side_effect=ValueError("Chunk index out of range: 99"),
+        )
+        resp = client.delete("/api/analyses/j1/chunks/99")
+        assert resp.status_code == 400
+
+    def test_delete_chunk_not_completed(self, client, mock_analysis_service):
+        mock_analysis_service.delete_chunk = AsyncMock(
+            side_effect=ValueError("Analysis is not completed: j1"),
+        )
+        resp = client.delete("/api/analyses/j1/chunks/0")
+        assert resp.status_code == 400
+
+
 class TestRechunkEndpoint:
     def test_rechunk_success(self, client, mock_analysis_service):
         mock_analysis_service.rechunk = AsyncMock(
@@ -357,3 +466,74 @@ class TestRechunkEndpoint:
             },
         )
         assert resp.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# Remote chunking path — hybrid local chunking from Serve's document_json
+# ---------------------------------------------------------------------------
+
+
+class TestRemoteChunkingPath:
+    """Verify that chunking works on document_json produced by Serve (remote mode)."""
+
+    @pytest.mark.asyncio
+    async def test_rechunk_with_serve_document_json(self):
+        """AnalysisService.rechunk() works with a LocalChunker even in remote mode."""
+        from infra.local_chunker import LocalChunker
+        from services.analysis_service import AnalysisService
+
+        chunker = LocalChunker()
+        analysis_repo = AsyncMock()
+        document_repo = AsyncMock()
+        converter = AsyncMock()  # ServeConverter mock — not used for rechunking
+
+        service = AnalysisService(
+            converter=converter,
+            analysis_repo=analysis_repo,
+            document_repo=document_repo,
+            chunker=chunker,
+        )
+
+        # Simulate a completed job with document_json from Serve
+        job = AnalysisJob(id="j-remote", document_id="d1")
+        job.mark_running()
+        job.mark_completed(
+            markdown="# Title\nParagraph text here.",
+            html="<h1>Title</h1><p>Paragraph text here.</p>",
+            pages_json="[]",
+            document_json=json.dumps(
+                {
+                    "schema_name": "DoclingDocument",
+                    "version": "1.0.0",
+                    "name": "test",
+                    "origin": {
+                        "mimetype": "application/pdf",
+                        "filename": "test.pdf",
+                        "binary_hash": 0,
+                    },
+                    "furniture": {
+                        "self_ref": "#/furniture",
+                        "children": [],
+                        "content_layer": "furniture",
+                    },
+                    "body": {"self_ref": "#/body", "children": [], "content_layer": "body"},
+                    "groups": [],
+                    "texts": [],
+                    "pictures": [],
+                    "tables": [],
+                    "key_value_items": [],
+                    "form_items": [],
+                    "pages": {},
+                }
+            ),
+        )
+        analysis_repo.find_by_id = AsyncMock(return_value=job)
+        analysis_repo.update_chunks = AsyncMock(return_value=True)
+
+        chunks = await service.rechunk(
+            "j-remote",
+            {"chunker_type": "hybrid", "max_tokens": 512},
+        )
+
+        assert isinstance(chunks, list)
+        analysis_repo.update_chunks.assert_called_once()

document-parser/tests/test_docling_agent_reasoning.py

@@ -0,0 +1,265 @@
+"""Tests for `infra.docling_agent_reasoning.DoclingAgentReasoningRunner`.
+
+docling-agent + mellea + docling-core are NOT installed in the CI test env
+(heavy deps). We stub the modules via `sys.modules` injection so the tests
+cover the real adapter code path without bringing in Ollama or any LLM
+client.
+
+Concurrency check (R3): the previous implementation mutated
+`os.environ["OLLAMA_HOST"]` on every request, which raced when two requests
+arrived with different hosts. The new design commits the host once at
+construction time — these tests assert that property holds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import types
+from unittest.mock import MagicMock
+
+import pytest
+
+from domain.ports import ReasoningParseError, ReasoningRunner
+from infra.llm.ollama_provider import OllamaProvider
+
+
+@pytest.fixture
+def stub_docling_agent(monkeypatch: pytest.MonkeyPatch):
+    """Inject fake `docling_agent.agents` + `docling_core.types.doc.document`
+    + `mellea.backends.model_ids` modules so the adapter's lazy imports
+    resolve to our stubs.
+
+    Returns the stub `DoclingRAGAgent` class + agent instance + result so
+    tests can configure return values / side effects.
+    """
+    fake_result = MagicMock()
+    fake_result.answer = "stub answer"
+    fake_result.converged = True
+    fake_result.iterations = [
+        MagicMock(
+            model_dump=lambda: {
+                "iteration": 1,
+                "section_ref": "#/texts/0",
+                "reason": "looks relevant",
+                "section_text_length": 42,
+                "can_answer": True,
+                "response": "stub answer",
+            }
+        )
+    ]
+
+    agent_instance = MagicMock()
+    agent_instance._rag_loop.return_value = fake_result
+    agent_class = MagicMock(return_value=agent_instance)
+
+    fake_agents_mod = types.ModuleType("docling_agent.agents")
+    fake_agents_mod.DoclingRAGAgent = agent_class
+    fake_root_mod = types.ModuleType("docling_agent")
+    fake_root_mod.agents = fake_agents_mod
+
+    fake_doc_class = MagicMock()
+    fake_doc_class.model_validate_json = MagicMock(return_value="fake-doc-instance")
+    fake_doc_mod = types.ModuleType("docling_core.types.doc.document")
+    fake_doc_mod.DoclingDocument = fake_doc_class
+
+    def fake_model_identifier(**kwargs):
+        m = MagicMock()
+        m.ollama_name = kwargs.get("ollama_name")
+        m.openai_name = kwargs.get("openai_name")
+        return m
+
+    fake_model_ids_mod = types.ModuleType("mellea.backends.model_ids")
+    fake_model_ids_mod.ModelIdentifier = fake_model_identifier
+    fake_backends_mod = types.ModuleType("mellea.backends")
+    fake_backends_mod.model_ids = fake_model_ids_mod
+    fake_mellea_mod = types.ModuleType("mellea")
+    fake_mellea_mod.backends = fake_backends_mod
+
+    monkeypatch.setitem(sys.modules, "docling_agent", fake_root_mod)
+    monkeypatch.setitem(sys.modules, "docling_agent.agents", fake_agents_mod)
+    monkeypatch.setitem(sys.modules, "docling_core.types.doc.document", fake_doc_mod)
+    monkeypatch.setitem(sys.modules, "mellea", fake_mellea_mod)
+    monkeypatch.setitem(sys.modules, "mellea.backends", fake_backends_mod)
+    monkeypatch.setitem(sys.modules, "mellea.backends.model_ids", fake_model_ids_mod)
+
+    return agent_class, agent_instance, fake_result
+
+
+def _make_runner_with_stubbed_deps(
+    *,
+    host: str = "http://ollama:11434",
+    default_model_id: str = "gpt-oss:20b",
+):
+    """Build the runner bypassing the deps-check (we stubbed deps via
+    sys.modules but `import` inside `deps_present()` runs at import time —
+    see how the adapter handles it)."""
+    from infra.docling_agent_reasoning import DoclingAgentReasoningRunner
+
+    # Force the deps_present check to True regardless of the test env.
+    runner = DoclingAgentReasoningRunner.__new__(DoclingAgentReasoningRunner)
+    runner._provider = OllamaProvider(host=host, default_model_id=default_model_id)
+    runner._deps_ok = True
+    os.environ["OLLAMA_HOST"] = host
+    return runner
+
+
+class TestProtocolConformance:
+    def test_runner_satisfies_reasoning_runner_protocol(self) -> None:
+        """R13 — adapter is structurally a `ReasoningRunner`."""
+        runner = _make_runner_with_stubbed_deps()
+        assert isinstance(runner, ReasoningRunner)
+
+
+class TestProviderRejection:
+    def test_rejects_non_ollama_provider(self) -> None:
+        from infra.docling_agent_reasoning import DoclingAgentReasoningRunner
+
+        class _FakeProvider:
+            type = "openai"
+            host = "x"
+            default_model_id = "y"
+
+            def health_check(self) -> bool:
+                return True
+
+        with pytest.raises(NotImplementedError, match="Ollama"):
+            DoclingAgentReasoningRunner(provider=_FakeProvider())  # type: ignore[arg-type]
+
+
+class TestRunHappyPath:
+    @pytest.mark.asyncio
+    async def test_returns_domain_reasoning_result(self, stub_docling_agent) -> None:
+        runner = _make_runner_with_stubbed_deps()
+
+        result = await runner.run(
+            document_json='{"stub": true}',
+            query="What is this?",
+        )
+
+        assert result.answer == "stub answer"
+        assert result.converged is True
+        assert len(result.iterations) == 1
+        it = result.iterations[0]
+        assert it.iteration == 1
+        assert it.section_ref == "#/texts/0"
+        assert it.can_answer is True
+
+    @pytest.mark.asyncio
+    async def test_uses_default_model_id_when_not_overridden(self, stub_docling_agent) -> None:
+        agent_class, _, _ = stub_docling_agent
+        runner = _make_runner_with_stubbed_deps(default_model_id="custom-model:7b")
+
+        await runner.run(document_json="{}", query="Q")
+
+        agent_class.assert_called_once()
+        passed = agent_class.call_args.kwargs["model_id"]
+        assert passed.ollama_name == "custom-model:7b"
+
+    @pytest.mark.asyncio
+    async def test_per_call_model_id_override_wins(self, stub_docling_agent) -> None:
+        agent_class, _, _ = stub_docling_agent
+        runner = _make_runner_with_stubbed_deps(default_model_id="default:7b")
+
+        await runner.run(document_json="{}", query="Q", model_id="override:13b")
+
+        passed = agent_class.call_args.kwargs["model_id"]
+        assert passed.ollama_name == "override:13b"
+
+    @pytest.mark.asyncio
+    async def test_calls_rag_loop_with_query_and_doc(self, stub_docling_agent) -> None:
+        _, agent_instance, _ = stub_docling_agent
+        runner = _make_runner_with_stubbed_deps()
+
+        await runner.run(document_json="{}", query="Hello?")
+
+        agent_instance._rag_loop.assert_called_once()
+        kwargs = agent_instance._rag_loop.call_args.kwargs
+        assert kwargs["query"] == "Hello?"
+        assert kwargs["doc"] == "fake-doc-instance"
+
+
+class TestRunUpstreamFailure:
+    @pytest.mark.asyncio
+    async def test_indexerror_translates_to_parse_error(self, stub_docling_agent) -> None:
+        """docling-agent's known IndexError → domain `ReasoningParseError`."""
+        _, agent_instance, _ = stub_docling_agent
+        agent_instance._rag_loop.side_effect = IndexError("list index out of range")
+        runner = _make_runner_with_stubbed_deps(default_model_id="granite4:micro-h")
+
+        with pytest.raises(ReasoningParseError) as exc_info:
+            await runner.run(document_json="{}", query="Q")
+
+        assert exc_info.value.model_id == "granite4:micro-h"
+
+    @pytest.mark.asyncio
+    async def test_other_exceptions_propagate(self, stub_docling_agent) -> None:
+        _, agent_instance, _ = stub_docling_agent
+        agent_instance._rag_loop.side_effect = RuntimeError("Ollama unreachable")
+        runner = _make_runner_with_stubbed_deps()
+
+        with pytest.raises(RuntimeError, match="Ollama unreachable"):
+            await runner.run(document_json="{}", query="Q")
+
+
+class TestHostIsolation:
+    """R3 — host is committed at construction; concurrent calls don't race
+    on `os.environ["OLLAMA_HOST"]` because it isn't mutated per-request.
+    """
+
+    def test_host_committed_at_construction(self) -> None:
+        os.environ.pop("OLLAMA_HOST", None)
+        runner = _make_runner_with_stubbed_deps(host="http://specific-host:11434")
+        assert os.environ["OLLAMA_HOST"] == "http://specific-host:11434"
+        # Explicit ref to silence unused-var lint
+        assert runner._provider.host == "http://specific-host:11434"
+
+    @pytest.mark.asyncio
+    async def test_concurrent_runs_do_not_mutate_env(self, stub_docling_agent) -> None:
+        """Two concurrent `run()` calls on the SAME runner — env stays put.
+
+        With the previous design, each request mutated OLLAMA_HOST per-call.
+        Now nothing in `run()` should touch os.environ — assert that.
+        """
+        runner = _make_runner_with_stubbed_deps(host="http://stable:11434")
+        os.environ["OLLAMA_HOST"] = "http://stable:11434"
+
+        observed: list[str] = []
+
+        # Use a fresh side_effect that records env at call time.
+        _, agent_instance, _ = stub_docling_agent
+        original = agent_instance._rag_loop
+
+        def record_env(*args, **kwargs):
+            observed.append(os.environ.get("OLLAMA_HOST", ""))
+            return original.return_value
+
+        agent_instance._rag_loop = record_env
+
+        await asyncio.gather(
+            runner.run(document_json="{}", query="Q1"),
+            runner.run(document_json="{}", query="Q2"),
+            runner.run(document_json="{}", query="Q3"),
+        )
+
+        assert observed == [
+            "http://stable:11434",
+            "http://stable:11434",
+            "http://stable:11434",
+        ]
+
+
+class TestDepsPresent:
+    def test_deps_present_returns_false_when_modules_missing(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """When docling-agent/mellea aren't importable, the wiring code
+        should know not to instantiate the runner."""
+        monkeypatch.setitem(sys.modules, "docling_agent", None)
+        monkeypatch.setitem(sys.modules, "docling_agent.agents", None)
+        monkeypatch.setitem(sys.modules, "mellea", None)
+
+        from infra.docling_agent_reasoning import deps_present
+
+        assert deps_present() is False

document-parser/tests/test_docling_graph.py

@@ -0,0 +1,398 @@
+"""Tests for `infra.docling_graph.build_graph_payload`.
+
+The fixture mirrors the DoclingDocument shape used in
+`tests/neo4j/test_tree_writer.py` so any structural drift between the two
+consumers (TreeWriter -> Neo4j, builder -> SQLite reasoning-graph) surfaces
+immediately.
+"""
+
+from __future__ import annotations
+
+import json
+
+from infra.docling_graph import build_graph_payload
+
+FIXTURE = {
+    "name": "fixture.pdf",
+    "pages": {
+        "1": {"page_no": 1, "size": {"width": 595, "height": 842}},
+        "2": {"page_no": 2, "size": {"width": 595, "height": 842}},
+    },
+    "body": {
+        "self_ref": "#/body",
+        "children": [
+            {"$ref": "#/texts/0"},
+            {"$ref": "#/texts/1"},
+            {"$ref": "#/texts/2"},
+            {"$ref": "#/tables/0"},
+        ],
+    },
+    "texts": [
+        {
+            "self_ref": "#/texts/0",
+            "parent": {"$ref": "#/body"},
+            "label": "section_header",
+            "text": "Introduction",
+            "level": 1,
+            "prov": [{"page_no": 1, "bbox": {"l": 10, "t": 10, "r": 100, "b": 30}}],
+        },
+        {
+            "self_ref": "#/texts/1",
+            "parent": {"$ref": "#/body"},
+            "label": "paragraph",
+            "text": "First paragraph on page 1.",
+            "prov": [{"page_no": 1, "bbox": {"l": 10, "t": 40, "r": 500, "b": 80}}],
+        },
+        {
+            "self_ref": "#/texts/2",
+            "parent": {"$ref": "#/body"},
+            "label": "paragraph",
+            "text": "Continued on page 2.",
+            "prov": [{"page_no": 2, "bbox": {"l": 10, "t": 40, "r": 500, "b": 80}}],
+        },
+    ],
+    "tables": [
+        {
+            "self_ref": "#/tables/0",
+            "parent": {"$ref": "#/body"},
+            "label": "table",
+            "text": "",
+            "data": {"num_rows": 2, "num_cols": 2},
+            "prov": [{"page_no": 2, "bbox": {"l": 10, "t": 90, "r": 500, "b": 200}}],
+        }
+    ],
+    "pictures": [],
+    "groups": [],
+}
+
+
+def _ids(items, group=None):
+    return [i["id"] for i in items if group is None or i.get("group") == group]
+
+
+def _types(edges):
+    return [e["type"] for e in edges]
+
+
+def test_builds_document_page_and_element_nodes():
+    payload = build_graph_payload(json.dumps(FIXTURE), doc_id="doc-fixture", title="fixture.pdf")
+    assert payload.doc_id == "doc-fixture"
+    assert payload.page_count == 2
+    assert payload.truncated is False
+
+    assert _ids(payload.nodes, group="document") == ["doc::doc-fixture"]
+    assert set(_ids(payload.nodes, group="page")) == {"page::1", "page::2"}
+    assert set(_ids(payload.nodes, group="element")) == {
+        "elem::#/texts/0",
+        "elem::#/texts/1",
+        "elem::#/texts/2",
+        "elem::#/tables/0",
+    }
+
+
+def test_element_keeps_docling_label_and_specific_label():
+    payload = build_graph_payload(json.dumps(FIXTURE), doc_id="doc-fixture")
+    by_id = {n["id"]: n for n in payload.nodes}
+    section = by_id["elem::#/texts/0"]
+    para = by_id["elem::#/texts/1"]
+    table = by_id["elem::#/tables/0"]
+
+    # Specific label mirrors TreeWriter's `_LABEL_MAP`.
+    assert section["label"] == "SectionHeader"
+    assert para["label"] == "Paragraph"
+    assert table["label"] == "Table"
+    # Docling's original label is preserved (lowercased) for filtering.
+    assert section["docling_label"] == "section_header"
+    assert para["docling_label"] == "paragraph"
+
+
+def test_provs_are_carried_on_element_nodes():
+    payload = build_graph_payload(json.dumps(FIXTURE), doc_id="doc-fixture")
+    by_id = {n["id"]: n for n in payload.nodes}
+    para = by_id["elem::#/texts/1"]
+    assert para["prov_page"] == 1
+    assert len(para["provs"]) == 1
+    assert para["provs"][0]["bbox_l"] == 10.0
+    assert para["provs"][0]["page_no"] == 1
+
+
+def test_has_root_parent_next_and_on_page_edges():
+    payload = build_graph_payload(json.dumps(FIXTURE), doc_id="doc-fixture")
+    types = _types(payload.edges)
+    # 4 top-level children => 4 HAS_ROOT.
+    assert types.count("HAS_ROOT") == 4
+    # 4 elements in reading order => 3 NEXT edges.
+    assert types.count("NEXT") == 3
+    # 4 elements each on 1 page => 4 ON_PAGE edges.
+    assert types.count("ON_PAGE") == 4
+    # No PARENT_OF in this flat fixture (all parents are #/body).
+    assert types.count("PARENT_OF") == 0
+
+
+def test_on_page_edges_point_to_correct_pages():
+    payload = build_graph_payload(json.dumps(FIXTURE), doc_id="doc-fixture")
+    on_page = [(e["source"], e["target"]) for e in payload.edges if e["type"] == "ON_PAGE"]
+    assert ("elem::#/texts/0", "page::1") in on_page
+    assert ("elem::#/texts/2", "page::2") in on_page
+    assert ("elem::#/tables/0", "page::2") in on_page
+
+
+def test_on_page_dedups_when_element_has_multiple_provs_same_page():
+    # Paragraph with two provs on the same page — we expect ONE ON_PAGE edge.
+    fixture = {
+        **FIXTURE,
+        "texts": [
+            {
+                "self_ref": "#/texts/0",
+                "parent": {"$ref": "#/body"},
+                "label": "paragraph",
+                "text": "Split across two provs same page",
+                "prov": [
+                    {"page_no": 1, "bbox": {"l": 0, "t": 0, "r": 10, "b": 10}},
+                    {"page_no": 1, "bbox": {"l": 0, "t": 20, "r": 10, "b": 30}},
+                ],
+            },
+        ],
+        "tables": [],
+        "body": {"self_ref": "#/body", "children": [{"$ref": "#/texts/0"}]},
+    }
+    payload = build_graph_payload(json.dumps(fixture), doc_id="doc-split")
+    on_page = [e for e in payload.edges if e["type"] == "ON_PAGE"]
+    assert len(on_page) == 1
+
+
+def test_parent_of_edges_when_items_are_nested():
+    fixture = {
+        "pages": {"1": {"page_no": 1, "size": {"width": 595, "height": 842}}},
+        "body": {"self_ref": "#/body", "children": [{"$ref": "#/texts/0"}]},
+        "texts": [
+            {
+                "self_ref": "#/texts/0",
+                "parent": {"$ref": "#/body"},
+                "label": "section_header",
+                "text": "Chapter",
+                "level": 1,
+                "children": [{"$ref": "#/texts/1"}],
+                "prov": [{"page_no": 1, "bbox": {"l": 0, "t": 0, "r": 10, "b": 10}}],
+            },
+            {
+                "self_ref": "#/texts/1",
+                "parent": {"$ref": "#/texts/0"},
+                "label": "paragraph",
+                "text": "Body",
+                "prov": [{"page_no": 1, "bbox": {"l": 0, "t": 20, "r": 10, "b": 30}}],
+            },
+        ],
+        "tables": [],
+        "pictures": [],
+        "groups": [],
+    }
+    payload = build_graph_payload(json.dumps(fixture), doc_id="doc-nested")
+    parents = [(e["source"], e["target"]) for e in payload.edges if e["type"] == "PARENT_OF"]
+    assert parents == [("elem::#/texts/0", "elem::#/texts/1")]
+    roots = [e for e in payload.edges if e["type"] == "HAS_ROOT"]
+    assert len(roots) == 1  # only the section is a direct child of body
+    # NEXT follows DFS order: #/texts/0 -> #/texts/1
+    nexts = [(e["source"], e["target"]) for e in payload.edges if e["type"] == "NEXT"]
+    assert nexts == [("elem::#/texts/0", "elem::#/texts/1")]
+
+
+def test_truncated_when_page_count_exceeds_cap():
+    fixture = {
+        **FIXTURE,
+        "pages": {str(i): {"page_no": i, "size": {"width": 1, "height": 1}} for i in range(1, 12)},
+    }
+    payload = build_graph_payload(json.dumps(fixture), doc_id="doc-big", max_pages=10)
+    assert payload.truncated is True
+    assert payload.page_count == 11
+    assert payload.nodes == []
+    assert payload.edges == []
+
+
+def test_title_is_surfaced_on_document_node():
+    payload = build_graph_payload(json.dumps(FIXTURE), doc_id="doc-fixture", title="My Doc.pdf")
+    doc_node = next(n for n in payload.nodes if n["group"] == "document")
+    assert doc_node["title"] == "My Doc.pdf"
+
+
+def test_inline_group_collapses_into_single_paragraph():
+    """Issue #197: an InlineGroup + N child `text` items must yield ONE
+    Paragraph node carrying the joined text and the union of children's provs."""
+    fixture = {
+        "pages": {"1": {"page_no": 1, "size": {"width": 595, "height": 842}}},
+        "body": {
+            "self_ref": "#/body",
+            "children": [{"$ref": "#/texts/0"}, {"$ref": "#/groups/0"}],
+        },
+        "texts": [
+            {
+                "self_ref": "#/texts/0",
+                "parent": {"$ref": "#/body"},
+                "label": "section_header",
+                "text": "Heading",
+                "level": 1,
+                "prov": [{"page_no": 1, "bbox": {"l": 10, "t": 10, "r": 100, "b": 30}}],
+            },
+            {
+                "self_ref": "#/texts/1",
+                "parent": {"$ref": "#/groups/0"},
+                "label": "text",
+                "text": "Hello",
+                "prov": [{"page_no": 1, "bbox": {"l": 10, "t": 40, "r": 50, "b": 60}}],
+            },
+            {
+                "self_ref": "#/texts/2",
+                "parent": {"$ref": "#/groups/0"},
+                "label": "text",
+                "text": "world",
+                "prov": [{"page_no": 1, "bbox": {"l": 55, "t": 40, "r": 100, "b": 60}}],
+            },
+            {
+                "self_ref": "#/texts/3",
+                "parent": {"$ref": "#/groups/0"},
+                "label": "text",
+                "text": "!",
+                "prov": [{"page_no": 1, "bbox": {"l": 105, "t": 40, "r": 110, "b": 60}}],
+            },
+        ],
+        "tables": [],
+        "pictures": [],
+        "groups": [
+            {
+                "self_ref": "#/groups/0",
+                "parent": {"$ref": "#/body"},
+                "label": "inline",
+                "children": [
+                    {"$ref": "#/texts/1"},
+                    {"$ref": "#/texts/2"},
+                    {"$ref": "#/texts/3"},
+                ],
+            },
+        ],
+    }
+    payload = build_graph_payload(json.dumps(fixture), doc_id="doc-inline")
+
+    # Section header + collapsed inline group only — NOT 5 (+3 style runs).
+    elements = [n for n in payload.nodes if n.get("group") == "element"]
+    assert {e["self_ref"] for e in elements} == {"#/texts/0", "#/groups/0"}
+
+    inline = next(n for n in elements if n["self_ref"] == "#/groups/0")
+    assert inline["label"] == "Paragraph"
+    assert inline["text"] == "Hello world !"
+    # Provs union: 3 children x 1 prov each = 3 provs on the collapsed node.
+    assert len(inline["provs"]) == 3
+    assert all(p.get("page_no") == 1 for p in inline["provs"])
+
+    # NEXT follows the post-collapse reading order — section_header → inline only.
+    nexts = [(e["source"], e["target"]) for e in payload.edges if e["type"] == "NEXT"]
+    assert nexts == [("elem::#/texts/0", "elem::#/groups/0")]
+
+    # ON_PAGE edges still wire the surviving elements to the page (one per
+    # element, deduped by `seen_pages`).
+    on_page = [e for e in payload.edges if e["type"] == "ON_PAGE"]
+    assert sorted(e["source"] for e in on_page) == ["elem::#/groups/0", "elem::#/texts/0"]
+
+
+def test_picture_internal_labels_are_skipped():
+    """Issue #197: a Picture's `children` (flowchart / diagram text labels
+    extracted by Docling's layout model) must not become standalone graph
+    nodes — they drown the figure in dozens of tiny labels. The picture
+    itself stays, and a caption (separate `parent` chain on body) is
+    unaffected."""
+    fixture = {
+        "pages": {"1": {"page_no": 1, "size": {"width": 595, "height": 842}}},
+        "body": {
+            "self_ref": "#/body",
+            "children": [{"$ref": "#/texts/0"}, {"$ref": "#/pictures/0"}],
+        },
+        "texts": [
+            # Caption — separate item under body, referenced from the picture's
+            # `captions` field (not its `children`). Survives the collapse.
+            {
+                "self_ref": "#/texts/0",
+                "parent": {"$ref": "#/body"},
+                "label": "caption",
+                "text": "Figure 1: Sketch of Docling's pipelines.",
+                "prov": [{"page_no": 1, "bbox": {"l": 0, "t": 700, "r": 500, "b": 720}}],
+            },
+            # Internal labels of the figure (flowchart boxes). Live in
+            # `texts[]` with `parent` pointing at the picture.
+            *[
+                {
+                    "self_ref": f"#/texts/{i}",
+                    "parent": {"$ref": "#/pictures/0"},
+                    "label": "text",
+                    "text": label,
+                    "prov": [
+                        {
+                            "page_no": 1,
+                            "bbox": {"l": 100 + i * 30, "t": 200, "r": 130 + i * 30, "b": 220},
+                        }
+                    ],
+                }
+                for i, label in enumerate(
+                    ["Parse", "Build", "Enrich", "Assemble", "Document"], start=1
+                )
+            ],
+        ],
+        "tables": [],
+        "pictures": [
+            {
+                "self_ref": "#/pictures/0",
+                "parent": {"$ref": "#/body"},
+                "label": "picture",
+                "children": [
+                    {"$ref": "#/texts/1"},
+                    {"$ref": "#/texts/2"},
+                    {"$ref": "#/texts/3"},
+                    {"$ref": "#/texts/4"},
+                    {"$ref": "#/texts/5"},
+                ],
+                "captions": [{"$ref": "#/texts/0"}],
+                "prov": [{"page_no": 1, "bbox": {"l": 90, "t": 100, "r": 510, "b": 600}}],
+            }
+        ],
+        "groups": [],
+    }
+    payload = build_graph_payload(json.dumps(fixture), doc_id="doc-pic")
+
+    elements = [n for n in payload.nodes if n.get("group") == "element"]
+    refs = {e["self_ref"] for e in elements}
+    # Picture + caption only — the 5 internal labels must be dropped.
+    assert refs == {"#/pictures/0", "#/texts/0"}
+
+    # Picture keeps its own label / text / prov (no inline-style override).
+    pic = next(e for e in elements if e["self_ref"] == "#/pictures/0")
+    assert pic["label"] == "Figure"
+    assert pic["docling_label"] == "picture"
+
+    # No PARENT_OF edges from the picture to its (skipped) children.
+    parent_edges = [e for e in payload.edges if e["type"] == "PARENT_OF"]
+    assert all(e["source"] != "elem::#/pictures/0" for e in parent_edges)
+
+    # NEXT chain only includes surviving elements.
+    next_targets = [e["target"] for e in payload.edges if e["type"] == "NEXT"]
+    assert all(t in {"elem::#/texts/0", "elem::#/pictures/0"} for t in next_targets)
+
+
+def test_element_text_is_capped_at_200_chars():
+    long = "x" * 500
+    fixture = {
+        "pages": {"1": {"page_no": 1, "size": {"width": 1, "height": 1}}},
+        "body": {"self_ref": "#/body", "children": [{"$ref": "#/texts/0"}]},
+        "texts": [
+            {
+                "self_ref": "#/texts/0",
+                "parent": {"$ref": "#/body"},
+                "label": "paragraph",
+                "text": long,
+                "prov": [{"page_no": 1}],
+            }
+        ],
+        "tables": [],
+        "pictures": [],
+        "groups": [],
+    }
+    payload = build_graph_payload(json.dumps(fixture), doc_id="doc-long")
+    para = next(n for n in payload.nodes if n.get("self_ref") == "#/texts/0")
+    assert len(para["text"]) == 200

document-parser/tests/test_embedding_client.py

@@ -0,0 +1,112 @@
+"""Tests for the embedding client adapter (infra.embedding_client).
+
+Mock httpx to validate adapter logic without running the embedding service.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from domain.ports import EmbeddingService
+from infra.embedding_client import _MAX_BATCH, EmbeddingClient
+
+# -- Protocol satisfaction -----------------------------------------------------
+
+
+class TestProtocolSatisfaction:
+    def test_satisfies_embedding_service_protocol(self) -> None:
+        client = EmbeddingClient("http://localhost:8001")
+        assert isinstance(client, EmbeddingService)
+
+
+# -- embed ---------------------------------------------------------------------
+
+
+class TestEmbed:
+    async def test_returns_empty_for_empty_input(self) -> None:
+        client = EmbeddingClient("http://localhost:8001")
+        result = await client.embed([])
+        assert result == []
+
+    async def test_calls_service_and_returns_embeddings(self) -> None:
+        client = EmbeddingClient("http://localhost:8001")
+        mock_response = MagicMock()
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {
+            "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+            "model": "all-MiniLM-L6-v2",
+            "dimension": 2,
+        }
+
+        mock_http_client = AsyncMock()
+        mock_http_client.post.return_value = mock_response
+        mock_http_client.__aenter__ = AsyncMock(return_value=mock_http_client)
+        mock_http_client.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("infra.embedding_client.httpx.AsyncClient", return_value=mock_http_client):
+            result = await client.embed(["hello", "world"])
+
+        assert result == [[0.1, 0.2], [0.3, 0.4]]
+        mock_http_client.post.assert_awaited_once_with(
+            "http://localhost:8001/embed",
+            json={"texts": ["hello", "world"]},
+        )
+
+    async def test_strips_trailing_slash_from_base_url(self) -> None:
+        client = EmbeddingClient("http://localhost:8001/")
+        mock_response = MagicMock()
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {"embeddings": [[0.1]], "model": "m", "dimension": 1}
+
+        mock_http_client = AsyncMock()
+        mock_http_client.post.return_value = mock_response
+        mock_http_client.__aenter__ = AsyncMock(return_value=mock_http_client)
+        mock_http_client.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("infra.embedding_client.httpx.AsyncClient", return_value=mock_http_client):
+            await client.embed(["test"])
+
+        mock_http_client.post.assert_awaited_once_with(
+            "http://localhost:8001/embed",
+            json={"texts": ["test"]},
+        )
+
+    async def test_splits_large_batches(self) -> None:
+        client = EmbeddingClient("http://localhost:8001")
+        texts = [f"text_{i}" for i in range(_MAX_BATCH + 10)]
+
+        call_count = 0
+
+        def make_response(batch_size: int) -> MagicMock:
+            resp = MagicMock()
+            resp.raise_for_status = MagicMock()
+            resp.json.return_value = {
+                "embeddings": [[0.1]] * batch_size,
+                "model": "m",
+                "dimension": 1,
+            }
+            return resp
+
+        async def mock_post(url: str, json: dict) -> MagicMock:
+            nonlocal call_count
+            call_count += 1
+            return make_response(len(json["texts"]))
+
+        mock_http_client = AsyncMock()
+        mock_http_client.post = mock_post
+        mock_http_client.__aenter__ = AsyncMock(return_value=mock_http_client)
+        mock_http_client.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("infra.embedding_client.httpx.AsyncClient", return_value=mock_http_client):
+            result = await client.embed(texts)
+
+        assert len(result) == _MAX_BATCH + 10
+        assert call_count == 2  # _MAX_BATCH + 10 remaining
+
+
+# -- max batch constant --------------------------------------------------------
+
+
+class TestMaxBatch:
+    def test_max_batch_is_256(self) -> None:
+        assert _MAX_BATCH == 256

document-parser/tests/test_graph_api.py

@@ -0,0 +1,114 @@
+"""Tests for `api.graph` — the `/graph` (Neo4j) and `/reasoning-graph`
+(SQLite) endpoints. Neo4j itself is not exercised here; `/graph` is covered
+by the integration tests under `tests/neo4j/`. This file focuses on the
+SQLite-backed reasoning endpoint and the error paths.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from api.graph import router
+from domain.models import AnalysisJob
+
+FIXTURE = {
+    "pages": {"1": {"page_no": 1, "size": {"width": 595, "height": 842}}},
+    "body": {"self_ref": "#/body", "children": [{"$ref": "#/texts/0"}]},
+    "texts": [
+        {
+            "self_ref": "#/texts/0",
+            "parent": {"$ref": "#/body"},
+            "label": "section_header",
+            "text": "Hello",
+            "level": 1,
+            "prov": [{"page_no": 1, "bbox": {"l": 0, "t": 0, "r": 10, "b": 10}}],
+        }
+    ],
+    "tables": [],
+    "pictures": [],
+    "groups": [],
+}
+
+
+def _job_with_doc_json() -> AnalysisJob:
+    job = AnalysisJob(document_id="doc-1")
+    job.document_filename = "hello.pdf"
+    job.mark_running()
+    job.mark_completed(
+        markdown="# Hello",
+        html="<h1>Hello</h1>",
+        pages_json="[]",
+        document_json=json.dumps(FIXTURE),
+        chunks_json="[]",
+    )
+    return job
+
+
+@pytest.fixture
+def mock_analysis_repo() -> AsyncMock:
+    repo = AsyncMock()
+    repo.find_latest_completed_by_document.return_value = _job_with_doc_json()
+    return repo
+
+
+@pytest.fixture
+def client(mock_analysis_repo: AsyncMock) -> TestClient:
+    app = FastAPI()
+    app.include_router(router)
+    app.state.analysis_repo = mock_analysis_repo
+    app.state.neo4j = None  # /reasoning-graph must not need Neo4j
+    return TestClient(app)
+
+
+class TestReasoningGraph:
+    def test_returns_payload_built_from_sqlite_json(self, client: TestClient) -> None:
+        resp = client.get("/api/documents/doc-1/reasoning-graph")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["doc_id"] == "doc-1"
+        assert data["page_count"] == 1
+        assert data["truncated"] is False
+
+        groups = {n["group"] for n in data["nodes"]}
+        assert groups == {"document", "page", "element"}
+
+        edge_types = {e["type"] for e in data["edges"]}
+        # HAS_ROOT + ON_PAGE expected; NEXT absent (single element so no chain).
+        assert edge_types == {"HAS_ROOT", "ON_PAGE"}
+
+    def test_404_when_no_completed_analysis(
+        self, client: TestClient, mock_analysis_repo: AsyncMock
+    ) -> None:
+        mock_analysis_repo.find_latest_completed_by_document.return_value = None
+        resp = client.get("/api/documents/doc-1/reasoning-graph")
+        assert resp.status_code == 404
+
+    def test_404_when_analysis_has_no_document_json(
+        self, client: TestClient, mock_analysis_repo: AsyncMock
+    ) -> None:
+        job = AnalysisJob(document_id="doc-1")
+        job.mark_running()
+        job.mark_completed(
+            markdown="", html="", pages_json="[]", document_json=None, chunks_json="[]"
+        )
+        mock_analysis_repo.find_latest_completed_by_document.return_value = job
+        resp = client.get("/api/documents/doc-1/reasoning-graph")
+        assert resp.status_code == 404
+
+    def test_does_not_need_neo4j(self, client: TestClient) -> None:
+        # `app.state.neo4j = None` and the endpoint still serves — proves the
+        # reasoning graph is fully decoupled from the Neo4j provider.
+        resp = client.get("/api/documents/doc-1/reasoning-graph")
+        assert resp.status_code == 200
+
+
+class TestPrimeEndpointRemoved:
+    def test_graph_prime_endpoint_is_gone(self, client: TestClient) -> None:
+        # Guardrail — if someone reintroduces /graph/prime we want a failing test.
+        resp = client.post("/api/documents/doc-1/graph/prime")
+        assert resp.status_code in (404, 405)

document-parser/tests/test_ingestion_api.py

@@ -0,0 +1,187 @@
+"""Tests for the ingestion API endpoints (api.ingestion)."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from api.ingestion import router
+from domain.models import AnalysisJob
+from services.ingestion_service import IngestionResult
+
+
+@pytest.fixture
+def mock_ingestion_service() -> AsyncMock:
+    svc = AsyncMock()
+    svc.ingest.return_value = IngestionResult(
+        doc_id="doc-1", chunks_indexed=5, embedding_dimension=384
+    )
+    svc.delete_document.return_value = 3
+    return svc
+
+
+@pytest.fixture
+def mock_analysis_service() -> AsyncMock:
+    svc = AsyncMock()
+    job = AnalysisJob(document_id="doc-1")
+    job.document_filename = "test.pdf"
+    job.mark_running()
+    job.mark_completed(
+        markdown="# Test",
+        html="<h1>Test</h1>",
+        pages_json="[]",
+        document_json='{"doc": true}',
+        chunks_json='[{"text": "hello"}]',
+    )
+    svc.find_by_id.return_value = job
+    return svc
+
+
+@pytest.fixture
+def client(mock_ingestion_service: AsyncMock, mock_analysis_service: AsyncMock) -> TestClient:
+    app = FastAPI()
+    app.include_router(router)
+    app.state.ingestion_service = mock_ingestion_service
+    app.state.analysis_service = mock_analysis_service
+    return TestClient(app)
+
+
+class TestIngestAnalysis:
+    def test_ingest_success(self, client: TestClient) -> None:
+        resp = client.post("/api/ingestion/job-1")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["docId"] == "doc-1"
+        assert data["chunksIndexed"] == 5
+        assert data["embeddingDimension"] == 384
+
+    def test_ingest_not_found(self, client: TestClient, mock_analysis_service: AsyncMock) -> None:
+        mock_analysis_service.find_by_id.return_value = None
+        resp = client.post("/api/ingestion/missing")
+        assert resp.status_code == 404
+
+    def test_ingest_not_completed(
+        self, client: TestClient, mock_analysis_service: AsyncMock
+    ) -> None:
+        job = AnalysisJob(document_id="doc-1")
+        mock_analysis_service.find_by_id.return_value = job
+        resp = client.post("/api/ingestion/job-1")
+        assert resp.status_code == 400
+
+    def test_ingest_no_chunks(self, client: TestClient, mock_analysis_service: AsyncMock) -> None:
+        job = AnalysisJob(document_id="doc-1")
+        job.mark_running()
+        job.mark_completed(markdown="x", html="x", pages_json="[]")
+        mock_analysis_service.find_by_id.return_value = job
+        resp = client.post("/api/ingestion/job-1")
+        assert resp.status_code == 400
+
+
+class TestDeleteIngested:
+    def test_delete_success(self, client: TestClient) -> None:
+        resp = client.delete("/api/ingestion/doc-1")
+        assert resp.status_code == 204
+
+
+class TestIngestionStatus:
+    def test_available(self, client: TestClient) -> None:
+        resp = client.get("/api/ingestion/status")
+        assert resp.status_code == 200
+        assert resp.json()["available"] is True
+
+    def test_not_available(self) -> None:
+        app = FastAPI()
+        app.include_router(router)
+        app.state.ingestion_service = None
+        app.state.analysis_service = AsyncMock()
+        tc = TestClient(app)
+        resp = tc.get("/api/ingestion/status")
+        assert resp.status_code == 200
+        assert resp.json()["available"] is False
+
+
+class TestIngestionDisabled:
+    def test_router_not_mounted_returns_404(self) -> None:
+        """When ingestion service is None, router should not be mounted → 404."""
+        app = FastAPI()
+        # Do NOT include ingestion router — simulates main.py conditional mount
+        app.state.ingestion_service = None
+        app.state.analysis_service = AsyncMock()
+        tc = TestClient(app)
+        resp = tc.post("/api/ingestion/job-1")
+        assert resp.status_code == 404
+
+    def test_status_still_returns_503_when_router_mounted_but_service_none(self) -> None:
+        """If router is mounted but service is None, endpoints return 503."""
+        app = FastAPI()
+        app.include_router(router)
+        app.state.ingestion_service = None
+        app.state.analysis_service = AsyncMock()
+        tc = TestClient(app)
+        resp = tc.post("/api/ingestion/job-1")
+        assert resp.status_code == 503
+
+
+class TestStatusOpenSearch:
+    def test_status_with_opensearch_connected(
+        self, client: TestClient, mock_ingestion_service: AsyncMock
+    ) -> None:
+        mock_ingestion_service.ping.return_value = True
+        resp = client.get("/api/ingestion/status")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["available"] is True
+        assert data["opensearchConnected"] is True
+
+    def test_status_with_opensearch_disconnected(
+        self, client: TestClient, mock_ingestion_service: AsyncMock
+    ) -> None:
+        mock_ingestion_service.ping.return_value = False
+        resp = client.get("/api/ingestion/status")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["available"] is True
+        assert data["opensearchConnected"] is False
+
+
+class TestSearchEndpoint:
+    def test_search_success(self, client: TestClient, mock_ingestion_service: AsyncMock) -> None:
+        from domain.vector_schema import IndexedChunk, SearchResult
+
+        chunk = IndexedChunk(
+            doc_id="doc-1",
+            filename="test.pdf",
+            content="hello world",
+            embedding=[],
+            chunk_index=0,
+            chunk_type="text",
+            page_number=1,
+            headings=["Intro"],
+        )
+        mock_ingestion_service.search_fulltext.return_value = [
+            SearchResult(chunk=chunk, score=0.95)
+        ]
+        resp = client.get("/api/ingestion/search", params={"q": "hello"})
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["total"] == 1
+        assert data["query"] == "hello"
+        assert data["results"][0]["content"] == "hello world"
+        assert data["results"][0]["score"] == 0.95
+
+    def test_search_empty_query(self, client: TestClient) -> None:
+        resp = client.get("/api/ingestion/search", params={"q": ""})
+        assert resp.status_code == 422
+
+    def test_search_with_doc_filter(
+        self, client: TestClient, mock_ingestion_service: AsyncMock
+    ) -> None:
+        mock_ingestion_service.search_fulltext.return_value = []
+        resp = client.get("/api/ingestion/search", params={"q": "test", "doc_id": "doc-1"})
+        assert resp.status_code == 200
+        mock_ingestion_service.search_fulltext.assert_awaited_once_with(
+            "test", k=20, doc_id="doc-1"
+        )

document-parser/tests/test_ingestion_service.py

@@ -0,0 +1,186 @@
+"""Tests for the ingestion service (services.ingestion_service)."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock
+
+import pytest
+
+from services.ingestion_service import IngestionConfig, IngestionService
+
+
+def _make_chunks_json(count: int = 3, *, with_deleted: bool = False) -> str:
+    chunks = []
+    for i in range(count):
+        chunk = {
+            "text": f"chunk text {i}",
+            "headings": [f"Heading {i}"],
+            "sourcePage": i + 1,
+            "tokenCount": 10,
+            "bboxes": [{"page": i + 1, "bbox": [0.0, 0.0, 100.0, 50.0]}],
+        }
+        if with_deleted and i == count - 1:
+            chunk["deleted"] = True
+        chunks.append(chunk)
+    return json.dumps(chunks)
+
+
+@pytest.fixture
+def mock_embedding() -> AsyncMock:
+    svc = AsyncMock()
+    svc.embed.return_value = [[0.1, 0.2, 0.3]] * 3
+    return svc
+
+
+@pytest.fixture
+def mock_vector_store() -> AsyncMock:
+    store = AsyncMock()
+    store.ensure_index.return_value = None
+    store.delete_document.return_value = 0
+    store.index_chunks.return_value = 3
+    return store
+
+
+@pytest.fixture
+def service(mock_embedding: AsyncMock, mock_vector_store: AsyncMock) -> IngestionService:
+    return IngestionService(
+        embedding_service=mock_embedding,
+        vector_store=mock_vector_store,
+        config=IngestionConfig(index_name="test-idx", embedding_dimension=3),
+    )
+
+
+class TestIngest:
+    async def test_full_pipeline(
+        self, service: IngestionService, mock_embedding: AsyncMock, mock_vector_store: AsyncMock
+    ) -> None:
+        result = await service.ingest("doc-1", "test.pdf", _make_chunks_json(3))
+
+        assert result.doc_id == "doc-1"
+        assert result.chunks_indexed == 3
+        mock_embedding.embed.assert_awaited_once()
+        texts = mock_embedding.embed.call_args[0][0]
+        assert len(texts) == 3
+        mock_vector_store.ensure_index.assert_awaited_once()
+        mock_vector_store.delete_document.assert_awaited_once_with("test-idx", "doc-1")
+        mock_vector_store.index_chunks.assert_awaited_once()
+        indexed = mock_vector_store.index_chunks.call_args[0][1]
+        assert len(indexed) == 3
+        assert indexed[0].doc_id == "doc-1"
+        assert indexed[0].filename == "test.pdf"
+        assert indexed[0].embedding == [0.1, 0.2, 0.3]
+
+    async def test_skips_deleted_chunks(
+        self, service: IngestionService, mock_embedding: AsyncMock, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_embedding.embed.return_value = [[0.1, 0.2, 0.3]] * 2
+        mock_vector_store.index_chunks.return_value = 2
+        result = await service.ingest("doc-1", "test.pdf", _make_chunks_json(3, with_deleted=True))
+
+        assert result.chunks_indexed == 2
+        texts = mock_embedding.embed.call_args[0][0]
+        assert len(texts) == 2
+
+    async def test_empty_chunks(
+        self, service: IngestionService, mock_embedding: AsyncMock, mock_vector_store: AsyncMock
+    ) -> None:
+        result = await service.ingest("doc-1", "test.pdf", json.dumps([]))
+        assert result.chunks_indexed == 0
+        mock_embedding.embed.assert_not_awaited()
+
+    async def test_idempotent_deletes_old(
+        self, service: IngestionService, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_vector_store.delete_document.return_value = 5
+        await service.ingest("doc-1", "test.pdf", _make_chunks_json(3))
+        mock_vector_store.delete_document.assert_awaited_once_with("test-idx", "doc-1")
+
+    async def test_bbox_conversion(
+        self, service: IngestionService, mock_embedding: AsyncMock, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_embedding.embed.return_value = [[0.1, 0.2, 0.3]]
+        mock_vector_store.index_chunks.return_value = 1
+        await service.ingest("doc-1", "test.pdf", _make_chunks_json(1))
+        indexed = mock_vector_store.index_chunks.call_args[0][1]
+        bbox = indexed[0].bboxes[0]
+        assert bbox.x == 0.0
+        assert bbox.y == 0.0
+        assert bbox.w == 100.0
+        assert bbox.h == 50.0
+
+    async def test_with_binary_hash(
+        self, service: IngestionService, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_embedding = service._embedding
+        mock_embedding.embed.return_value = [[0.1]] * 1
+        await service.ingest("doc-1", "test.pdf", _make_chunks_json(1), binary_hash="abc123")
+        indexed = mock_vector_store.index_chunks.call_args[0][1]
+        assert indexed[0].origin is not None
+        assert indexed[0].origin.binary_hash == "abc123"
+
+
+class TestDeleteDocument:
+    async def test_delegates_to_vector_store(
+        self, service: IngestionService, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_vector_store.delete_document.return_value = 3
+        result = await service.delete_document("doc-1")
+        assert result == 3
+
+
+class TestSearch:
+    async def test_embeds_and_searches(
+        self, service: IngestionService, mock_embedding: AsyncMock, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_embedding.embed.return_value = [[0.5, 0.6, 0.7]]
+        mock_vector_store.search_similar.return_value = []
+        await service.search("test query", k=5)
+        mock_embedding.embed.assert_awaited_once_with(["test query"])
+        mock_vector_store.search_similar.assert_awaited_once()
+
+
+class TestSearchFulltext:
+    async def test_delegates_to_vector_store(
+        self, service: IngestionService, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_vector_store.search_fulltext.return_value = []
+        await service.search_fulltext("hello world", k=5)
+        mock_vector_store.search_fulltext.assert_awaited_once_with(
+            "test-idx", "hello world", k=5, doc_id=None
+        )
+
+    async def test_filters_by_doc_id(
+        self, service: IngestionService, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_vector_store.search_fulltext.return_value = []
+        await service.search_fulltext("hello", doc_id="doc-1")
+        mock_vector_store.search_fulltext.assert_awaited_once_with(
+            "test-idx", "hello", k=20, doc_id="doc-1"
+        )
+
+
+class TestPing:
+    async def test_ping_success(
+        self, service: IngestionService, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_vector_store.ping.return_value = True
+        result = await service.ping()
+        assert result is True
+
+    async def test_ping_failure(
+        self, service: IngestionService, mock_vector_store: AsyncMock
+    ) -> None:
+        mock_vector_store.ping.side_effect = ConnectionError("down")
+        result = await service.ping()
+        assert result is False
+
+
+class TestEnsureIndex:
+    async def test_calls_vector_store(
+        self, service: IngestionService, mock_vector_store: AsyncMock
+    ) -> None:
+        await service.ensure_index()
+        mock_vector_store.ensure_index.assert_awaited_once()
+        call_args = mock_vector_store.ensure_index.call_args
+        assert call_args[0][0] == "test-idx"

document-parser/tests/test_models.py

@@ -58,7 +58,7 @@ class TestAnalysisJob:
         job.mark_running()
 
         assert job.status == AnalysisStatus.RUNNING
-        assert job.started_at is not None
+        assert isinstance(job.started_at, datetime)
 
     def test_mark_completed(self):
         job = AnalysisJob()
@@ -74,7 +74,8 @@ class TestAnalysisJob:
         assert job.content_markdown == "# Title"
         assert job.content_html == "<h1>Title</h1>"
         assert job.pages_json == '[{"page": 1}]'
-        assert job.completed_at is not None
+        assert isinstance(job.completed_at, datetime)
+        assert job.completed_at >= job.started_at
 
     def test_mark_failed(self):
         job = AnalysisJob()
@@ -84,7 +85,8 @@ class TestAnalysisJob:
 
         assert job.status == AnalysisStatus.FAILED
         assert job.error_message == "Something went wrong"
-        assert job.completed_at is not None
+        assert isinstance(job.completed_at, datetime)
+        assert job.completed_at >= job.started_at
 
     def test_status_transitions(self):
         """Test full lifecycle: PENDING -> RUNNING -> COMPLETED."""

document-parser/tests/test_ollama_provider.py

@@ -0,0 +1,82 @@
+"""Tests for `infra.llm.ollama_provider.OllamaProvider`.
+
+Network is stubbed via `httpx` MockTransport so the tests don't depend on a
+running Ollama instance.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+
+from domain.ports import LLMProvider
+from domain.value_objects import LLMProviderType
+from infra.llm.ollama_provider import OllamaProvider
+
+if TYPE_CHECKING:
+    import pytest
+
+
+def test_provider_satisfies_llmprovider_protocol() -> None:
+    """R13 — `OllamaProvider` is structurally a `LLMProvider`."""
+    p = OllamaProvider(host="http://localhost:11434", default_model_id="m")
+    assert isinstance(p, LLMProvider)
+
+
+def test_provider_exposes_type_host_default_model_id() -> None:
+    p = OllamaProvider(host="http://ollama:11434", default_model_id="gpt-oss:20b")
+    assert p.type is LLMProviderType.OLLAMA
+    assert p.host == "http://ollama:11434"
+    assert p.default_model_id == "gpt-oss:20b"
+
+
+def test_host_trailing_slash_is_stripped() -> None:
+    p = OllamaProvider(host="http://localhost:11434/", default_model_id="m")
+    assert p.host == "http://localhost:11434"
+
+
+def test_health_check_returns_true_on_200(monkeypatch: pytest.MonkeyPatch) -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/api/tags"
+        return httpx.Response(200, json={"models": []})
+
+    transport = httpx.MockTransport(handler)
+    real_get = httpx.get
+
+    def fake_get(url: str, **kwargs):  # type: ignore[no-untyped-def]
+        with httpx.Client(transport=transport) as client:
+            return client.get(url, **kwargs)
+
+    monkeypatch.setattr(httpx, "get", fake_get)
+    p = OllamaProvider(host="http://localhost:11434", default_model_id="m")
+    assert p.health_check() is True
+
+    # Restore (defensive, MonkeyPatch handles it but explicit is fine)
+    monkeypatch.setattr(httpx, "get", real_get)
+
+
+def test_health_check_returns_false_on_connection_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake_get(url: str, **kwargs):  # type: ignore[no-untyped-def]
+        raise httpx.ConnectError("connection refused")
+
+    monkeypatch.setattr(httpx, "get", fake_get)
+    p = OllamaProvider(host="http://nowhere:11434", default_model_id="m")
+    assert p.health_check() is False
+
+
+def test_health_check_returns_false_on_non_200(monkeypatch: pytest.MonkeyPatch) -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500)
+
+    transport = httpx.MockTransport(handler)
+
+    def fake_get(url: str, **kwargs):  # type: ignore[no-untyped-def]
+        with httpx.Client(transport=transport) as client:
+            return client.get(url, **kwargs)
+
+    monkeypatch.setattr(httpx, "get", fake_get)
+    p = OllamaProvider(host="http://localhost:11434", default_model_id="m")
+    assert p.health_check() is False

document-parser/tests/test_opensearch_store.py

@@ -0,0 +1,320 @@
+"""Tests for the OpenSearch adapter (infra.opensearch_store).
+
+These tests mock the AsyncOpenSearch client to validate adapter logic
+without requiring a running OpenSearch instance.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from domain.ports import VectorStore
+from domain.vector_schema import (
+    ChunkBboxEntry,
+    ChunkOrigin,
+    DocItemRef,
+    IndexedChunk,
+    SearchResult,
+    build_index_mapping,
+)
+from infra.opensearch_store import OpenSearchStore, _hit_to_indexed_chunk, _hit_to_result
+
+# -- Fixtures -----------------------------------------------------------------
+
+
+def _make_chunk(
+    doc_id: str = "doc-1",
+    chunk_index: int = 0,
+    content: str = "hello world",
+    embedding: list[float] | None = None,
+) -> IndexedChunk:
+    return IndexedChunk(
+        doc_id=doc_id,
+        filename="test.pdf",
+        content=content,
+        embedding=embedding or [0.1, 0.2, 0.3],
+        chunk_index=chunk_index,
+        chunk_type="text",
+        page_number=1,
+        bboxes=[ChunkBboxEntry(page=1, x=0.0, y=0.0, w=100.0, h=50.0)],
+        headings=["Chapter 1"],
+        doc_items=[DocItemRef(self_ref="#/texts/0", label="text")],
+        origin=ChunkOrigin(binary_hash="abc123", filename="test.pdf"),
+    )
+
+
+def _make_hit(
+    doc_id: str = "doc-1",
+    chunk_index: int = 0,
+    score: float = 0.95,
+    content: str = "hello world",
+) -> dict:
+    return {
+        "_id": f"{doc_id}_{chunk_index}",
+        "_score": score,
+        "_source": {
+            "doc_id": doc_id,
+            "filename": "test.pdf",
+            "content": content,
+            "chunk_index": chunk_index,
+            "chunk_type": "text",
+            "page_number": 1,
+            "bboxes": [{"page": 1, "x": 0.0, "y": 0.0, "w": 100.0, "h": 50.0}],
+            "headings": ["Chapter 1"],
+            "doc_items": [{"self_ref": "#/texts/0", "label": "text"}],
+            "origin": {"binary_hash": "abc123", "filename": "test.pdf"},
+        },
+    }
+
+
+@pytest.fixture
+def store() -> OpenSearchStore:
+    return OpenSearchStore("http://localhost:9200")
+
+
+@pytest.fixture
+def mock_client(store: OpenSearchStore) -> AsyncMock:
+    client = AsyncMock()
+    store._client = client
+    return client
+
+
+# -- Protocol satisfaction -----------------------------------------------------
+
+
+class TestProtocolSatisfaction:
+    def test_satisfies_vector_store_protocol(self) -> None:
+        """OpenSearchStore structurally satisfies VectorStore Protocol."""
+        store = OpenSearchStore("http://localhost:9200")
+        assert isinstance(store, VectorStore)
+
+
+# -- Hit deserialization -------------------------------------------------------
+
+
+class TestHitDeserialization:
+    def test_hit_to_indexed_chunk(self) -> None:
+        hit = _make_hit()
+        chunk = _hit_to_indexed_chunk(hit)
+        assert isinstance(chunk, IndexedChunk)
+        assert chunk.doc_id == "doc-1"
+        assert chunk.content == "hello world"
+        assert chunk.chunk_index == 0
+        assert chunk.page_number == 1
+        assert len(chunk.bboxes) == 1
+        assert chunk.bboxes[0].w == 100.0
+        assert len(chunk.doc_items) == 1
+        assert chunk.doc_items[0].label == "text"
+        assert chunk.origin is not None
+        assert chunk.origin.binary_hash == "abc123"
+
+    def test_hit_to_indexed_chunk_no_origin(self) -> None:
+        hit = _make_hit()
+        hit["_source"]["origin"] = None
+        chunk = _hit_to_indexed_chunk(hit)
+        assert chunk.origin is None
+
+    def test_hit_to_indexed_chunk_missing_optional_fields(self) -> None:
+        hit = _make_hit()
+        del hit["_source"]["bboxes"]
+        del hit["_source"]["headings"]
+        del hit["_source"]["doc_items"]
+        del hit["_source"]["origin"]
+        chunk = _hit_to_indexed_chunk(hit)
+        assert chunk.bboxes == []
+        assert chunk.headings == []
+        assert chunk.doc_items == []
+        assert chunk.origin is None
+
+    def test_hit_to_result(self) -> None:
+        hit = _make_hit(score=0.87)
+        result = _hit_to_result(hit)
+        assert isinstance(result, SearchResult)
+        assert result.score == 0.87
+        assert result.chunk.doc_id == "doc-1"
+
+
+# -- ensure_index --------------------------------------------------------------
+
+
+class TestEnsureIndex:
+    async def test_creates_index_when_not_exists(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        mock_client.indices.exists.return_value = False
+        mapping = build_index_mapping()
+        await store.ensure_index("test-index", mapping)
+        mock_client.indices.create.assert_awaited_once_with(index="test-index", body=mapping)
+
+    async def test_noop_when_index_exists(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        mock_client.indices.exists.return_value = True
+        await store.ensure_index("test-index", {})
+        mock_client.indices.create.assert_not_awaited()
+
+
+# -- index_chunks --------------------------------------------------------------
+
+
+class TestIndexChunks:
+    async def test_bulk_indexes_chunks(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        chunks = [_make_chunk(chunk_index=0), _make_chunk(chunk_index=1)]
+        mock_client.bulk.return_value = {
+            "errors": False,
+            "items": [
+                {"index": {"_id": "doc-1_0", "status": 201}},
+                {"index": {"_id": "doc-1_1", "status": 201}},
+            ],
+        }
+        count = await store.index_chunks("test-index", chunks)
+        assert count == 2
+        mock_client.bulk.assert_awaited_once()
+
+    async def test_returns_zero_for_empty_list(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        count = await store.index_chunks("test-index", [])
+        assert count == 0
+        mock_client.bulk.assert_not_awaited()
+
+    async def test_counts_partial_failures(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        chunks = [_make_chunk(chunk_index=0), _make_chunk(chunk_index=1)]
+        mock_client.bulk.return_value = {
+            "errors": True,
+            "items": [
+                {"index": {"_id": "doc-1_0", "status": 201}},
+                {"index": {"_id": "doc-1_1", "error": {"reason": "mapping"}}},
+            ],
+        }
+        count = await store.index_chunks("test-index", chunks)
+        assert count == 1
+
+    async def test_bulk_body_structure(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        chunk = _make_chunk(doc_id="d1", chunk_index=3)
+        mock_client.bulk.return_value = {
+            "errors": False,
+            "items": [{"index": {"_id": "d1_3", "status": 201}}],
+        }
+        await store.index_chunks("idx", [chunk])
+        call_body = mock_client.bulk.call_args[1]["body"]
+        assert call_body[0] == {"index": {"_index": "idx", "_id": "d1_3"}}
+        assert call_body[1]["doc_id"] == "d1"
+        assert call_body[1]["chunk_index"] == 3
+
+
+# -- search_similar ------------------------------------------------------------
+
+
+class TestSearchSimilar:
+    async def test_knn_search(self, store: OpenSearchStore, mock_client: AsyncMock) -> None:
+        mock_client.search.return_value = {"hits": {"hits": [_make_hit(score=0.99)]}}
+        results = await store.search_similar("idx", [0.1, 0.2, 0.3], k=5)
+        assert len(results) == 1
+        assert results[0].score == 0.99
+        call_body = mock_client.search.call_args[1]["body"]
+        assert call_body["query"]["knn"]["embedding"]["vector"] == [0.1, 0.2, 0.3]
+        assert call_body["query"]["knn"]["embedding"]["k"] == 5
+
+    async def test_knn_search_with_doc_filter(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        mock_client.search.return_value = {"hits": {"hits": []}}
+        await store.search_similar("idx", [0.1], doc_id="doc-42")
+        call_body = mock_client.search.call_args[1]["body"]
+        assert call_body["query"]["knn"]["embedding"]["filter"] == {"term": {"doc_id": "doc-42"}}
+
+    async def test_knn_search_no_filter_by_default(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        mock_client.search.return_value = {"hits": {"hits": []}}
+        await store.search_similar("idx", [0.1])
+        call_body = mock_client.search.call_args[1]["body"]
+        assert "filter" not in call_body["query"]["knn"]["embedding"]
+
+
+# -- get_chunks ----------------------------------------------------------------
+
+
+class TestGetChunks:
+    async def test_retrieves_by_doc_id(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        mock_client.search.return_value = {
+            "hits": {"hits": [_make_hit(chunk_index=0), _make_hit(chunk_index=1)]}
+        }
+        results = await store.get_chunks("idx", "doc-1")
+        assert len(results) == 2
+        call_body = mock_client.search.call_args[1]["body"]
+        assert call_body["query"] == {"term": {"doc_id": "doc-1"}}
+        assert call_body["sort"] == [{"chunk_index": {"order": "asc"}}]
+
+    async def test_respects_limit(self, store: OpenSearchStore, mock_client: AsyncMock) -> None:
+        mock_client.search.return_value = {"hits": {"hits": []}}
+        await store.get_chunks("idx", "doc-1", limit=50)
+        call_body = mock_client.search.call_args[1]["body"]
+        assert call_body["size"] == 50
+
+
+# -- delete_document -----------------------------------------------------------
+
+
+class TestDeleteDocument:
+    async def test_deletes_by_doc_id(self, store: OpenSearchStore, mock_client: AsyncMock) -> None:
+        mock_client.delete_by_query.return_value = {"deleted": 5}
+        count = await store.delete_document("idx", "doc-1")
+        assert count == 5
+        call_body = mock_client.delete_by_query.call_args[1]["body"]
+        assert call_body["query"] == {"term": {"doc_id": "doc-1"}}
+
+    async def test_returns_zero_on_not_found(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        from opensearchpy import NotFoundError
+
+        mock_client.delete_by_query.side_effect = NotFoundError(404, "index_not_found")
+        count = await store.delete_document("idx", "doc-1")
+        assert count == 0
+
+
+# -- search_fulltext -----------------------------------------------------------
+
+
+class TestSearchFulltext:
+    async def test_fulltext_search(self, store: OpenSearchStore, mock_client: AsyncMock) -> None:
+        mock_client.search.return_value = {
+            "hits": {"hits": [_make_hit(content="matching text", score=1.5)]}
+        }
+        results = await store.search_fulltext("idx", "matching")
+        assert len(results) == 1
+        assert results[0].chunk.content == "matching text"
+        call_body = mock_client.search.call_args[1]["body"]
+        assert {"match": {"content": "matching"}} in call_body["query"]["bool"]["must"]
+
+    async def test_fulltext_search_with_doc_filter(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        mock_client.search.return_value = {"hits": {"hits": []}}
+        await store.search_fulltext("idx", "query", doc_id="doc-5")
+        call_body = mock_client.search.call_args[1]["body"]
+        must_clauses = call_body["query"]["bool"]["must"]
+        assert {"term": {"doc_id": "doc-5"}} in must_clauses
+
+
+# -- close ---------------------------------------------------------------------
+
+
+class TestClose:
+    async def test_close_delegates_to_client(
+        self, store: OpenSearchStore, mock_client: AsyncMock
+    ) -> None:
+        await store.close()
+        mock_client.close.assert_awaited_once()

document-parser/tests/test_pipeline_options.py

@@ -53,7 +53,8 @@ class TestBuildConverter:
         assert opts.generate_page_images is False
         assert opts.generate_picture_images is False
         assert opts.images_scale == 1.0
-        assert opts.document_timeout is not None
+        # default document timeout is 120s (cf. infra/settings.py)
+        assert opts.document_timeout == 120.0
 
     def test_ocr_disabled(self):
         conv = build_converter(ConversionOptions(do_ocr=False))

document-parser/tests/test_reasoning_api.py

@@ -0,0 +1,248 @@
+"""Tests for `api.reasoning` — the HTTP layer over a `ReasoningRunner` port.
+
+The API layer is decoupled from docling-agent / mellea / docling-core. Tests
+inject a fake `ReasoningRunner` on `app.state.reasoning_runner` and assert on
+HTTP status / payload + on what the runner was called with.
+
+Adapter behaviour (the actual docling-agent integration) is tested separately
+in `tests/test_docling_agent_reasoning.py`.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from api.reasoning import router
+from domain.models import AnalysisJob
+from domain.ports import ReasoningParseError
+from domain.value_objects import ReasoningIteration, ReasoningResult
+
+
+def _job_with_doc_json() -> AnalysisJob:
+    job = AnalysisJob(document_id="doc-1")
+    job.document_filename = "hello.pdf"
+    job.mark_running()
+    job.mark_completed(
+        markdown="# Hello",
+        html="<h1>Hello</h1>",
+        pages_json="[]",
+        document_json='{"stub": true}',
+        chunks_json="[]",
+    )
+    return job
+
+
+def _sample_result() -> ReasoningResult:
+    return ReasoningResult(
+        answer="stub answer",
+        converged=True,
+        iterations=[
+            ReasoningIteration(
+                iteration=1,
+                section_ref="#/texts/0",
+                reason="looks relevant",
+                section_text_length=42,
+                can_answer=True,
+                response="stub answer",
+            )
+        ],
+    )
+
+
+class _FakeRunner:
+    """In-memory ReasoningRunner. Records the last call so tests can assert
+    on the args without touching docling-agent."""
+
+    def __init__(
+        self,
+        *,
+        result: ReasoningResult | None = None,
+        is_available: bool = True,
+        raises: Exception | None = None,
+    ) -> None:
+        self._result = result or _sample_result()
+        self._is_available = is_available
+        self._raises = raises
+        self.last_call: dict | None = None
+
+    @property
+    def is_available(self) -> bool:
+        return self._is_available
+
+    async def run(
+        self,
+        *,
+        document_json: str,
+        query: str,
+        model_id: str | None = None,
+    ) -> ReasoningResult:
+        self.last_call = {
+            "document_json": document_json,
+            "query": query,
+            "model_id": model_id,
+        }
+        if self._raises is not None:
+            raise self._raises
+        return self._result
+
+
+@pytest.fixture
+def mock_analysis_repo() -> AsyncMock:
+    repo = AsyncMock()
+    repo.find_latest_completed_by_document.return_value = _job_with_doc_json()
+    return repo
+
+
+def _make_client(*, runner: _FakeRunner | None, repo: AsyncMock) -> TestClient:
+    app = FastAPI()
+    app.include_router(router)
+    app.state.analysis_repo = repo
+    app.state.reasoning_runner = runner
+    return TestClient(app)
+
+
+class TestReasoningDisabled:
+    def test_503_when_runner_not_wired(self, mock_analysis_repo: AsyncMock) -> None:
+        client = _make_client(runner=None, repo=mock_analysis_repo)
+        resp = client.post("/api/documents/doc-1/reasoning", json={"query": "Q"})
+        assert resp.status_code == 503
+        assert "REASONING_ENABLED" in resp.json()["detail"]
+
+    def test_503_when_runner_unavailable(self, mock_analysis_repo: AsyncMock) -> None:
+        runner = _FakeRunner(is_available=False)
+        client = _make_client(runner=runner, repo=mock_analysis_repo)
+        resp = client.post("/api/documents/doc-1/reasoning", json={"query": "Q"})
+        assert resp.status_code == 503
+
+
+class TestReasoningValidation:
+    def test_400_when_query_empty(self, mock_analysis_repo: AsyncMock) -> None:
+        client = _make_client(runner=_FakeRunner(), repo=mock_analysis_repo)
+        resp = client.post("/api/documents/doc-1/reasoning", json={"query": "   "})
+        assert resp.status_code == 400
+
+    def test_404_when_no_completed_analysis(self, mock_analysis_repo: AsyncMock) -> None:
+        mock_analysis_repo.find_latest_completed_by_document.return_value = None
+        client = _make_client(runner=_FakeRunner(), repo=mock_analysis_repo)
+        resp = client.post("/api/documents/doc-1/reasoning", json={"query": "Q"})
+        assert resp.status_code == 404
+
+
+class TestReasoningSuccess:
+    def test_returns_reasoning_result_shape(self, mock_analysis_repo: AsyncMock) -> None:
+        runner = _FakeRunner()
+        client = _make_client(runner=runner, repo=mock_analysis_repo)
+
+        resp = client.post("/api/documents/doc-1/reasoning", json={"query": "What is this?"})
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["answer"] == "stub answer"
+        assert data["converged"] is True
+        assert len(data["iterations"]) == 1
+        it = data["iterations"][0]
+        assert it["iteration"] == 1
+        assert it["section_ref"] == "#/texts/0"
+        assert it["can_answer"] is True
+        assert it["section_text_length"] == 42
+
+    def test_passes_query_and_doc_json_to_runner(self, mock_analysis_repo: AsyncMock) -> None:
+        runner = _FakeRunner()
+        client = _make_client(runner=runner, repo=mock_analysis_repo)
+
+        client.post("/api/documents/doc-1/reasoning", json={"query": "Hello?"})
+
+        assert runner.last_call is not None
+        assert runner.last_call["query"] == "Hello?"
+        assert runner.last_call["document_json"] == '{"stub": true}'
+
+    def test_no_model_override_passes_none(self, mock_analysis_repo: AsyncMock) -> None:
+        runner = _FakeRunner()
+        client = _make_client(runner=runner, repo=mock_analysis_repo)
+
+        client.post("/api/documents/doc-1/reasoning", json={"query": "Q"})
+
+        assert runner.last_call is not None
+        assert runner.last_call["model_id"] is None
+
+    def test_per_request_model_id_override_wins(self, mock_analysis_repo: AsyncMock) -> None:
+        runner = _FakeRunner()
+        client = _make_client(runner=runner, repo=mock_analysis_repo)
+
+        client.post(
+            "/api/documents/doc-1/reasoning",
+            json={"query": "Q", "model_id": "override:13b"},
+        )
+
+        assert runner.last_call is not None
+        assert runner.last_call["model_id"] == "override:13b"
+
+    def test_iterations_with_multiple_steps_serialize_correctly(
+        self, mock_analysis_repo: AsyncMock
+    ) -> None:
+        """R6 — trace serializable on >=2 iterations, all fields preserved."""
+        result = ReasoningResult(
+            answer="final",
+            converged=False,
+            iterations=[
+                ReasoningIteration(
+                    iteration=1,
+                    section_ref="#/texts/0",
+                    reason="r1",
+                    section_text_length=10,
+                    can_answer=False,
+                    response="not yet",
+                ),
+                ReasoningIteration(
+                    iteration=2,
+                    section_ref="#/texts/5",
+                    reason="r2",
+                    section_text_length=20,
+                    can_answer=True,
+                    response="final",
+                ),
+            ],
+        )
+        runner = _FakeRunner(result=result)
+        client = _make_client(runner=runner, repo=mock_analysis_repo)
+
+        resp = client.post("/api/documents/doc-1/reasoning", json={"query": "Q"})
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["converged"] is False
+        assert [it["iteration"] for it in data["iterations"]] == [1, 2]
+        assert [it["section_ref"] for it in data["iterations"]] == [
+            "#/texts/0",
+            "#/texts/5",
+        ]
+        assert data["iterations"][0]["can_answer"] is False
+        assert data["iterations"][1]["can_answer"] is True
+
+
+class TestReasoningUpstreamFailure:
+    def test_502_when_runner_raises_parse_error(self, mock_analysis_repo: AsyncMock) -> None:
+        """The model couldn't produce a parseable JSON answer after retries."""
+        runner = _FakeRunner(
+            raises=ReasoningParseError(model_id="granite4:micro-h", reason="no parseable answer")
+        )
+        client = _make_client(runner=runner, repo=mock_analysis_repo)
+
+        resp = client.post(
+            "/api/documents/doc-1/reasoning",
+            json={"query": "Quelle tarification ?"},
+        )
+        assert resp.status_code == 502
+        detail = resp.json()["detail"]
+        assert "granite4:micro-h" in detail
+        assert "parseable" in detail or "rephrase" in detail
+
+    def test_500_for_other_unexpected_errors(self, mock_analysis_repo: AsyncMock) -> None:
+        runner = _FakeRunner(raises=RuntimeError("Ollama unreachable"))
+        client = _make_client(runner=runner, repo=mock_analysis_repo)
+
+        resp = client.post("/api/documents/doc-1/reasoning", json={"query": "Q"})
+        assert resp.status_code == 500
+        assert "Ollama unreachable" in resp.json()["detail"]

document-parser/tests/test_repos.py

@@ -1,5 +1,7 @@
 """Tests for persistence repositories using a temporary SQLite database."""
 
+from datetime import datetime
+
 import pytest
 
 from domain.models import AnalysisJob, AnalysisStatus, Document
@@ -121,7 +123,7 @@ class TestAnalysisRepo:
 
         found = await analysis_repo.find_by_id("job-1")
         assert found.status == AnalysisStatus.RUNNING
-        assert found.started_at is not None
+        assert isinstance(found.started_at, datetime)
 
     async def test_update_status_completed(self, document_repo, analysis_repo):
         await self._insert_doc(document_repo)
@@ -153,6 +155,49 @@ class TestAnalysisRepo:
         deleted = await analysis_repo.delete("nonexistent")
         assert deleted is False
 
+    async def test_find_latest_completed_by_document(self, document_repo, analysis_repo):
+        """Reasoning tunnel helper: latest COMPLETED analysis with document_json."""
+        await self._insert_doc(document_repo)
+
+        # Each job must be insert()'d before update_status can touch it.
+        # Scenarios: pending (excluded — not COMPLETED), old completed without
+        # document_json (excluded — NULL json), recent completed with
+        # document_json (the one we want), running (excluded).
+        pending = AnalysisJob(id="job-pending", document_id="doc-1")
+        await analysis_repo.insert(pending)
+
+        old_completed = AnalysisJob(id="job-old", document_id="doc-1")
+        await analysis_repo.insert(old_completed)
+        old_completed.mark_running()
+        old_completed.mark_completed(markdown="", html="", pages_json="[]")
+        await analysis_repo.update_status(old_completed)
+
+        latest = AnalysisJob(id="job-latest", document_id="doc-1")
+        await analysis_repo.insert(latest)
+        latest.mark_running()
+        latest.mark_completed(
+            markdown="md",
+            html="<p/>",
+            pages_json="[]",
+            document_json='{"body":{"children":[]},"texts":[]}',
+        )
+        await analysis_repo.update_status(latest)
+
+        running = AnalysisJob(id="job-running", document_id="doc-1")
+        await analysis_repo.insert(running)
+        running.mark_running()
+        await analysis_repo.update_status(running)
+
+        found = await analysis_repo.find_latest_completed_by_document("doc-1")
+        assert found is not None
+        assert found.id == "job-latest"
+        assert found.document_json == '{"body":{"children":[]},"texts":[]}'
+
+    async def test_find_latest_completed_by_document_none(self, document_repo, analysis_repo):
+        await self._insert_doc(document_repo)
+        found = await analysis_repo.find_latest_completed_by_document("doc-1")
+        assert found is None
+
     async def test_delete_by_document(self, document_repo, analysis_repo):
         await self._insert_doc(document_repo)
         for i in range(3):

document-parser/tests/test_serve_converter.py

@@ -39,7 +39,6 @@ class TestBuildFormData:
         assert data["do_picture_classification"] == "false"
         assert data["do_picture_description"] == "false"
         assert data["include_images"] == "false"
-        assert data["generate_page_images"] == "false"
         assert data["images_scale"] == "1.0"
         assert set(data["to_formats"]) == {"md", "html", "json"}
 
@@ -56,9 +55,14 @@ class TestBuildFormData:
         assert data["images_scale"] == "2.0"
         assert data["include_images"] == "true"
 
-    def test_page_range_included_when_set(self):
+    def test_no_generate_page_images_field(self):
+        """generate_page_images is a PdfPipelineOptions field, not a Serve field."""
+        data = _build_form_data(ConversionOptions())
+        assert "generate_page_images" not in data
+
+    def test_page_range_as_repeated_fields(self):
         data = _build_form_data(ConversionOptions(), page_range=(11, 20))
-        assert data["page_range"] == "11-20"
+        assert data["page_range"] == ["11", "20"]
 
     def test_page_range_absent_when_none(self):
         data = _build_form_data(ConversionOptions())
@@ -90,7 +94,10 @@ class TestParseResponse:
         assert result.content_html == "<h1>Hello</h1>"
         assert result.page_count == 1
         assert result.pages[0].width == 612.0
+        # document_json mirrors the json_content stub
         assert result.document_json is not None
+        assert '"texts"' in result.document_json
+        assert '"pages"' in result.document_json
 
     def test_response_with_elements(self):
         data = {
@@ -402,11 +409,12 @@ class TestServeConverterConvert:
         assert len(result.pages[0].elements) == 1
         assert result.pages[0].elements[0].type == "title"
 
-        # Verify form fields sent as dict with list for repeated keys
+        # Verify form fields sent correctly
         call_kwargs = mock_client.post.call_args
         sent_data = call_kwargs.kwargs.get("data", {})
         assert sent_data["do_ocr"] == "true"
         assert set(sent_data["to_formats"]) == {"md", "html", "json"}
+        assert "generate_page_images" not in sent_data
 
     @pytest.mark.asyncio
     async def test_http_error_raises(self, tmp_path):
@@ -414,6 +422,8 @@ class TestServeConverterConvert:
         test_file.write_bytes(b"%PDF-1.4 fake content")
 
         mock_response = MagicMock()
+        mock_response.status_code = 500
+        mock_response.text = "Internal Server Error"
         mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
             "Server Error",
             request=MagicMock(),
@@ -510,3 +520,17 @@ class TestConverterWiring:
             converter = _build_converter()
         assert isinstance(converter, ServeConverter)
         assert converter._api_key == "my-key"
+
+    def test_remote_engine_builds_chunker(self):
+        """Chunker must be available in remote mode (hybrid local chunking)."""
+        from infra.local_chunker import LocalChunker
+        from infra.settings import Settings
+
+        with patch(
+            "main.settings",
+            Settings(conversion_engine="remote", docling_serve_url="http://serve:5001"),
+        ):
+            from main import _build_chunker
+
+            chunker = _build_chunker()
+        assert isinstance(chunker, LocalChunker)

document-parser/tests/test_settings.py

@@ -18,7 +18,10 @@ class TestSettingsDefaults:
         assert s.lock_timeout == 300
         assert s.max_page_count == 0
         assert s.max_file_size_mb == 50
+        assert s.max_paste_image_size_mb == 10
+        assert s.paste_allowed_image_types == ["image/png", "image/jpeg", "image/webp"]
         assert s.batch_page_size == 0
+        assert s.opensearch_default_limit == 1000
         assert s.upload_dir == "./uploads"
         assert s.db_path == "./data/docling_studio.db"
         assert "http://localhost:3000" in s.cors_origins
@@ -75,6 +78,18 @@ class TestSettingsValidation:
         with pytest.raises(ValueError, match="max_file_size_mb must be >= 0"):
             Settings(max_file_size_mb=-1)
 
+    def test_negative_max_paste_image_size_mb_rejected(self):
+        import pytest
+
+        with pytest.raises(ValueError, match="max_paste_image_size_mb must be >= 0"):
+            Settings(max_paste_image_size_mb=-1)
+
+    def test_empty_paste_allowed_image_types_rejected(self):
+        import pytest
+
+        with pytest.raises(ValueError, match="paste_allowed_image_types must not be empty"):
+            Settings(paste_allowed_image_types=[])
+
     def test_zero_max_file_size_mb_accepted(self):
         s = Settings(max_file_size_mb=0)
         assert s.max_file_size_mb == 0
@@ -103,6 +118,12 @@ class TestSettingsValidation:
         with pytest.raises(ValueError, match="lock_timeout must be > 0"):
             Settings(lock_timeout=0)
 
+    def test_zero_opensearch_default_limit_rejected(self):
+        import pytest
+
+        with pytest.raises(ValueError, match="opensearch_default_limit must be >= 1"):
+            Settings(opensearch_default_limit=0)
+
     def test_invalid_table_mode_rejected(self):
         import pytest
 
@@ -146,6 +167,7 @@ class TestSettingsFromEnv:
         monkeypatch.setenv("MAX_PAGE_COUNT", "20")
         monkeypatch.setenv("MAX_FILE_SIZE_MB", "100")
         monkeypatch.setenv("BATCH_PAGE_SIZE", "15")
+        monkeypatch.setenv("OPENSEARCH_DEFAULT_LIMIT", "500")
         monkeypatch.setenv("UPLOAD_DIR", "/data/uploads")
         monkeypatch.setenv("DB_PATH", "/data/test.db")
         monkeypatch.setenv("CORS_ORIGINS", "http://a.com, http://b.com")
@@ -163,6 +185,7 @@ class TestSettingsFromEnv:
         assert s.max_page_count == 20
         assert s.max_file_size_mb == 100
         assert s.batch_page_size == 15
+        assert s.opensearch_default_limit == 500
         assert s.upload_dir == "/data/uploads"
         assert s.db_path == "/data/test.db"
         assert s.cors_origins == ["http://a.com", "http://b.com"]

document-parser/tests/test_vector_schema.py

@@ -0,0 +1,228 @@
+"""Tests for vector index schema — value objects and OpenSearch mapping."""
+
+from __future__ import annotations
+
+import pytest
+
+from domain.vector_schema import (
+    DEFAULT_EMBEDDING_DIMENSION,
+    DEFAULT_INDEX_NAME,
+    ChunkBboxEntry,
+    ChunkOrigin,
+    DocItemRef,
+    IndexedChunk,
+    SearchResult,
+    build_index_mapping,
+)
+
+
+class TestChunkBboxEntry:
+    def test_construction(self):
+        bbox = ChunkBboxEntry(page=1, x=10.0, y=20.0, w=100.0, h=50.0)
+        assert bbox.page == 1
+        assert bbox.x == 10.0
+        assert bbox.w == 100.0
+
+    def test_frozen(self):
+        bbox = ChunkBboxEntry(page=1, x=0, y=0, w=10, h=10)
+        with pytest.raises(AttributeError):
+            bbox.page = 2  # type: ignore[misc]
+
+
+class TestDocItemRef:
+    def test_construction(self):
+        ref = DocItemRef(self_ref="#/texts/0", label="text")
+        assert ref.self_ref == "#/texts/0"
+        assert ref.label == "text"
+
+
+class TestChunkOrigin:
+    def test_construction(self):
+        origin = ChunkOrigin(binary_hash="abc123", filename="doc.pdf")
+        assert origin.binary_hash == "abc123"
+        assert origin.filename == "doc.pdf"
+
+
+class TestIndexedChunk:
+    def _make_chunk(self, **overrides) -> IndexedChunk:
+        defaults = {
+            "doc_id": "doc-1",
+            "filename": "test.pdf",
+            "content": "Hello world",
+            "embedding": [0.1] * 384,
+            "chunk_index": 0,
+            "chunk_type": "text",
+            "page_number": 1,
+        }
+        defaults.update(overrides)
+        return IndexedChunk(**defaults)
+
+    def test_minimal_chunk(self):
+        chunk = self._make_chunk()
+        assert chunk.doc_id == "doc-1"
+        assert chunk.content == "Hello world"
+        assert chunk.bboxes == []
+        assert chunk.headings == []
+        assert chunk.doc_items == []
+        assert chunk.origin is None
+
+    def test_full_chunk(self):
+        chunk = self._make_chunk(
+            bboxes=[ChunkBboxEntry(page=1, x=10, y=20, w=100, h=50)],
+            headings=["Chapter 1", "Section A"],
+            doc_items=[DocItemRef(self_ref="#/texts/0", label="text")],
+            origin=ChunkOrigin(binary_hash="abc", filename="test.pdf"),
+        )
+        assert len(chunk.bboxes) == 1
+        assert chunk.headings == ["Chapter 1", "Section A"]
+        assert chunk.doc_items[0].label == "text"
+        assert chunk.origin.binary_hash == "abc"
+
+    def test_to_dict_minimal(self):
+        chunk = self._make_chunk()
+        d = chunk.to_dict()
+        assert d["doc_id"] == "doc-1"
+        assert d["filename"] == "test.pdf"
+        assert d["content"] == "Hello world"
+        assert d["embedding"] == [0.1] * 384
+        assert d["chunk_index"] == 0
+        assert d["chunk_type"] == "text"
+        assert d["page_number"] == 1
+        assert d["bboxes"] == []
+        assert d["headings"] == []
+        assert d["doc_items"] == []
+        assert "origin" not in d
+
+    def test_to_dict_full(self):
+        chunk = self._make_chunk(
+            bboxes=[ChunkBboxEntry(page=1, x=10.5, y=20.0, w=100.0, h=50.0)],
+            headings=["H1"],
+            doc_items=[DocItemRef(self_ref="#/texts/0", label="text")],
+            origin=ChunkOrigin(binary_hash="abc", filename="test.pdf"),
+        )
+        d = chunk.to_dict()
+        assert d["bboxes"] == [{"page": 1, "x": 10.5, "y": 20.0, "w": 100.0, "h": 50.0}]
+        assert d["headings"] == ["H1"]
+        assert d["doc_items"] == [{"self_ref": "#/texts/0", "label": "text"}]
+        assert d["origin"] == {"binary_hash": "abc", "filename": "test.pdf"}
+
+    def test_frozen(self):
+        chunk = self._make_chunk()
+        with pytest.raises(AttributeError):
+            chunk.content = "modified"  # type: ignore[misc]
+
+
+class TestBuildIndexMapping:
+    def test_default_dimension(self):
+        mapping = build_index_mapping()
+        props = mapping["mappings"]["properties"]
+        assert props["embedding"]["dimension"] == 384
+        assert props["embedding"]["type"] == "knn_vector"
+        assert props["embedding"]["method"]["engine"] == "faiss"
+        assert props["embedding"]["method"]["name"] == "hnsw"
+
+    def test_custom_dimension(self):
+        mapping = build_index_mapping(embedding_dimension=768)
+        assert mapping["mappings"]["properties"]["embedding"]["dimension"] == 768
+
+    def test_knn_enabled(self):
+        mapping = build_index_mapping()
+        assert mapping["settings"]["index"]["knn"] is True
+
+    def test_all_fields_present(self):
+        mapping = build_index_mapping()
+        props = mapping["mappings"]["properties"]
+        expected_fields = {
+            "doc_id",
+            "filename",
+            "content",
+            "embedding",
+            "chunk_index",
+            "chunk_type",
+            "page_number",
+            "bboxes",
+            "headings",
+            "doc_items",
+            "origin",
+        }
+        assert set(props.keys()) == expected_fields
+
+    def test_bboxes_nested_type(self):
+        mapping = build_index_mapping()
+        bboxes = mapping["mappings"]["properties"]["bboxes"]
+        assert bboxes["type"] == "nested"
+        assert "page" in bboxes["properties"]
+        assert "x" in bboxes["properties"]
+        assert "y" in bboxes["properties"]
+        assert "w" in bboxes["properties"]
+        assert "h" in bboxes["properties"]
+
+    def test_doc_items_nested_type(self):
+        mapping = build_index_mapping()
+        doc_items = mapping["mappings"]["properties"]["doc_items"]
+        assert doc_items["type"] == "nested"
+        assert "self_ref" in doc_items["properties"]
+        assert "label" in doc_items["properties"]
+
+    def test_origin_object_type(self):
+        mapping = build_index_mapping()
+        origin = mapping["mappings"]["properties"]["origin"]
+        assert origin["type"] == "object"
+        assert "binary_hash" in origin["properties"]
+        assert "filename" in origin["properties"]
+
+    def test_content_uses_standard_analyzer(self):
+        mapping = build_index_mapping()
+        content = mapping["mappings"]["properties"]["content"]
+        assert content["type"] == "text"
+        assert content["analyzer"] == "standard"
+
+    def test_keyword_fields(self):
+        mapping = build_index_mapping()
+        props = mapping["mappings"]["properties"]
+        for field_name in ("doc_id", "filename", "chunk_type"):
+            assert props[field_name]["type"] == "keyword", f"{field_name} should be keyword"
+
+    def test_integer_fields(self):
+        mapping = build_index_mapping()
+        props = mapping["mappings"]["properties"]
+        for field_name in ("chunk_index", "page_number"):
+            assert props[field_name]["type"] == "integer", f"{field_name} should be integer"
+
+
+class TestSearchResult:
+    def test_construction(self):
+        chunk = IndexedChunk(
+            doc_id="doc-1",
+            filename="test.pdf",
+            content="Hello",
+            embedding=[0.1] * 384,
+            chunk_index=0,
+            chunk_type="text",
+            page_number=1,
+        )
+        result = SearchResult(chunk=chunk, score=0.95)
+        assert result.chunk.content == "Hello"
+        assert result.score == 0.95
+
+    def test_frozen(self):
+        chunk = IndexedChunk(
+            doc_id="d",
+            filename="f",
+            content="c",
+            embedding=[],
+            chunk_index=0,
+            chunk_type="text",
+            page_number=1,
+        )
+        result = SearchResult(chunk=chunk, score=0.5)
+        with pytest.raises(AttributeError):
+            result.score = 0.9  # type: ignore[misc]
+
+
+class TestConstants:
+    def test_default_embedding_dimension(self):
+        assert DEFAULT_EMBEDDING_DIMENSION == 384
+
+    def test_default_index_name(self):
+        assert DEFAULT_INDEX_NAME == "docling-studio-chunks"

document-parser/tests/test_vector_store_port.py

@@ -0,0 +1,113 @@
+"""Tests for VectorStore port — verify the protocol contract is implementable."""
+
+from __future__ import annotations
+
+import pytest
+
+from domain.ports import VectorStore
+from domain.vector_schema import IndexedChunk, SearchResult
+
+
+class FakeVectorStore:
+    """Minimal concrete implementation to verify the protocol is implementable."""
+
+    async def ensure_index(self, index_name: str, mapping: dict) -> None:
+        pass
+
+    async def index_chunks(self, index_name: str, chunks: list[IndexedChunk]) -> int:
+        return len(chunks)
+
+    async def search_similar(
+        self,
+        index_name: str,
+        embedding: list[float],
+        *,
+        k: int = 10,
+        doc_id: str | None = None,
+    ) -> list[SearchResult]:
+        return []
+
+    async def get_chunks(
+        self,
+        index_name: str,
+        doc_id: str,
+        *,
+        limit: int = 1000,
+    ) -> list[SearchResult]:
+        return []
+
+    async def delete_document(self, index_name: str, doc_id: str) -> int:
+        return 0
+
+
+class TestVectorStorePort:
+    def test_fake_satisfies_protocol(self):
+        """A class implementing all methods is accepted as a VectorStore."""
+        store: VectorStore = FakeVectorStore()
+        assert store is not None
+
+    @pytest.mark.asyncio
+    async def test_ensure_index(self):
+        store = FakeVectorStore()
+        await store.ensure_index("test-index", {"mappings": {}})
+
+    @pytest.mark.asyncio
+    async def test_index_chunks(self):
+        store = FakeVectorStore()
+        chunk = IndexedChunk(
+            doc_id="d1",
+            filename="test.pdf",
+            content="Hello",
+            embedding=[0.1] * 384,
+            chunk_index=0,
+            chunk_type="text",
+            page_number=1,
+        )
+        count = await store.index_chunks("test-index", [chunk])
+        assert count == 1
+
+    @pytest.mark.asyncio
+    async def test_search_similar(self):
+        store = FakeVectorStore()
+        results = await store.search_similar("test-index", [0.1] * 384, k=5)
+        assert results == []
+
+    @pytest.mark.asyncio
+    async def test_search_similar_with_doc_filter(self):
+        store = FakeVectorStore()
+        results = await store.search_similar("test-index", [0.1] * 384, k=5, doc_id="d1")
+        assert results == []
+
+    @pytest.mark.asyncio
+    async def test_get_chunks(self):
+        store = FakeVectorStore()
+        results = await store.get_chunks("test-index", "d1")
+        assert results == []
+
+    @pytest.mark.asyncio
+    async def test_get_chunks_with_limit(self):
+        store = FakeVectorStore()
+        results = await store.get_chunks("test-index", "d1", limit=50)
+        assert results == []
+
+    @pytest.mark.asyncio
+    async def test_delete_document(self):
+        store = FakeVectorStore()
+        count = await store.delete_document("test-index", "d1")
+        assert count == 0
+
+    def test_protocol_methods_list(self):
+        """Verify the protocol exposes the expected methods."""
+        expected = {
+            "ensure_index",
+            "index_chunks",
+            "search_similar",
+            "get_chunks",
+            "delete_document",
+        }
+        protocol_methods = {
+            name
+            for name in dir(VectorStore)
+            if not name.startswith("_") and callable(getattr(VectorStore, name, None))
+        }
+        assert expected.issubset(protocol_methods)

e2e/api/src/test/resources/ingestion/ingest-and-verify.feature

@@ -0,0 +1,59 @@
+@e2e @ingestion
+Feature: Ingestion pipeline — PDF → chunks → embeddings → OpenSearch
+
+  Background:
+    * url baseUrl
+
+  Scenario: Upload PDF, analyze with chunking, ingest into OpenSearch, verify
+
+    # Step 1: Check ingestion is available
+    Given path '/api/ingestion/status'
+    When method GET
+    Then status 200
+    And match response.available == true
+
+    # Step 2: Upload a PDF
+    Given path '/api/documents/upload'
+    And multipart file file = { read: 'classpath:common/data/generated/medium.pdf', filename: 'medium.pdf', contentType: 'application/pdf' }
+    When method POST
+    Then status 200
+    * def docId = response.id
+
+    # Step 3: Create analysis with chunking
+    Given path '/api/analyses'
+    And request { documentId: '#(docId)', pipelineOptions: { doOcr: true, tableMode: 'fast' }, chunkingOptions: { chunkerType: 'hybrid', maxTokens: 256 } }
+    When method POST
+    Then status 200
+    * def jobId = response.id
+
+    # Step 4: Poll until completed
+    Given path '/api/analyses', jobId
+    And retry until response.status == 'COMPLETED' || response.status == 'FAILED'
+    When method GET
+    Then status 200
+    And match response.status == 'COMPLETED'
+    And match response.chunksJson == '#string'
+
+    # Step 5: Trigger ingestion
+    Given path '/api/ingestion', jobId
+    When method POST
+    Then status 200
+    And match response.docId == docId
+    And match response.chunksIndexed == '#number'
+    And assert response.chunksIndexed > 0
+    And match response.embeddingDimension == '#number'
+    And assert response.embeddingDimension > 0
+
+    # Step 6: Cleanup — delete ingested data
+    Given path '/api/ingestion', docId
+    When method DELETE
+    Then status 204
+
+    # Step 7: Cleanup — delete analysis and document
+    Given path '/api/analyses', jobId
+    When method DELETE
+    Then status 204
+
+    Given path '/api/documents', docId
+    When method DELETE
+    Then status 204