Skip to content

v0.7.0

Choose a tag to compare

View all tags
@pjmalandrino pjmalandrino released this 24 Aug 20:04
· 1 commit to main since this release
v0.7.0
fbd9608

This release replaces the standalone reasoning page with a trace surface built into the Parse view, where every citation resolves to a real element of your PDF. It also makes the reasoning stack configurable at runtime, and considerably slims down what the app tries to be.

✨ Added

Reasoning Trace v2 — timeline + Ask panel in the Parse view (#303)

Reasoning runs inside the Parse view of an analysis (Analyses → open a run), replacing the standalone /reasoning page.

  • A conversational Ask panel (composer + turn cards) drives the runs.
  • Each step carries a typed kind. The wire contract defines PLAN, RETRIEVE, RERANK, READ, VERIFY, ANSWER and MAP, reserved end-to-end so future agent phases render without a contract change. docling-agent 0.6.0's chunkless RAG loop emits only READ, so today every step in a real trace is a READ.
  • Timing: the run's wall-clock total is captured server-side and is real. Per-step durations are not reported by docling-agent 0.6.0, so the timeline renders in its uniform "step-order" mode with an explicit footnote rather than drawing bars that would be fiction. Per-step bars light up automatically once docling-agent#42 lands.
  • The part that works today, and is the point of the release: focusing a step reveals and scrolls the linked element across the PDF preview, the document tree and the Parse view — page flip, bbox highlight, ancestor auto-expand, and reverse selection. Citations are anchored in the document, not printed beside it.

Backend trace projection (#303)

A pure domain.trace_builder projects the raw docling-agent ReasoningResult onto a debugger-facing ReasoningTrace. A new ReasoningService owns the run (query validation, latest-analysis lookup, wall-clock timing), so api/documents/{id}/reasoning no longer reaches into app.state directly.

Runtime reasoning configuration from the admin panel (#317)

A Reasoning section in /settings enables/disables reasoning and sets the Ollama URL, default model and RAG max_iterations — without a backend restart. The runner and service are rebuilt in place and /api/health follows, so the Ask surface appears and disappears live.

  • Overrides persist in a new SQLite app_settings table. Env vars become bootstrap defaults; each field reports whether its value came from env or db, and reset to environment drops the overrides.
  • A test connection action probes the host and turns the model field into a select of the models actually installed.
  • Read-only diagnostics (docling-agent version + import path, provider, availability) make boot failures visible from the UI instead of the container logs.
  • New endpoints: GET / PUT / DELETE /api/config/reasoning and POST /api/config/reasoning/test. On HuggingFace deployments only GET is served — PUT, DELETE and the connection probe return 403, the probe included because it is a server-side request to a user-supplied URL.
  • max_iterations is now actually threaded into DoclingRAGAgent (new REASONING_MAX_ITERATIONS, default 5).

Analyses workspace

A dedicated Analyses section lists every run and opens its saved visualization independently of the document preview. A document can carry several analyses, and this is where the Parse view (and therefore reasoning) now lives.

🔧 Changed

  • The document workspace is preview-only. /docs/:id renders the document header and page preview. Chunking and ingestion controls are gone from it, related analyses are listed separately, and deleting a document explicitly confirms the analysis cascade.
  • Reasoning backend ported to the public run_with_trace() surface (#303). docling-agent is pinned to 0.6.0 and the adapter binds to a public, version-asserted API instead of the private _rag_loop(). A missing or unusable agent is detected at boot rather than on someone's first Ask, and an empty agent result maps to 502. (The IndexError guard around the agent's unguarded find_json_dicts(answer)[0] is still required and still present.)
  • Leaner dev stack. docker-compose.dev.yml now gates every service behind a profile: COMPOSE_PROFILES=default docker compose -f docker-compose.dev.yml up starts only the frontend and the SQLite-backed parser. graph adds Neo4j, ingestion adds OpenSearch + Dashboards + embedding, remote adds Docling Serve. ⚠️ A bare docker compose -f docker-compose.dev.yml up now starts nothing — COMPOSE_PROFILES is mandatory. The production docker-compose.yml is unchanged.

🗑️ Removed

  • Standalone v1 reasoning surface (#303): the graph-overlay reasoning workspace and its /reasoning page are gone, replaced by the Parse-view timeline. The old /reasoning and /reasoning/:docId routes are kept as redirects, so shared URLs don't 404.
  • Chunk and Ingest tabs in the document workspace: DocMode collapsed to parse only; ?mode=chunk and ?mode=ingest links resolve to the preview.
  • The Stores management UI: the stores list, detail, create, edit and query pages and their routes are removed (~1 500 lines). Store CRUD remains available over the API (/api/stores/*); the ingestion pipeline itself is unchanged.

⚠️ Use 0.7.1 for the reasoning features

This image does not ship the reasoning stack. release.yml did not pass the WITH_REASONING build flag, so docling-agent and mellea are absent from ghcr.io/scub-france/docling-studio:0.7.0-local: POST /api/documents/{docId}/reasoning responds 503 and the Ask surface stays hidden. The runtime panel can toggle reasoning, but it cannot install packages.

Fixed in 0.7.1 — use that image instead:

docker run -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  -e REASONING_ENABLED=true \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -e REASONING_MODEL_ID=gpt-oss:20b \
  ghcr.io/scub-france/docling-studio:0.7.1-local

Reasoning also needs a reachable Ollama with the model already pulled. On native Linux Docker, --network=host with OLLAMA_HOST=http://localhost:11434 works too. The lightweight remote image does not carry the reasoning stack.

Everything else in this release — the Analyses workspace, the simplified document workspace, the parsing and chunking pipeline — runs from the plain image.

Known limits

  • No streaming. A run is a single blocking request; steps appear when it completes.
  • Traces are session state. Conversation turns and traces live in the browser and vanish on reload.
  • Only READ steps, and no per-step timing, with docling-agent 0.6.0 (see above).
  • Token counts show as 0 until the runtime exposes usage stats; the UI hides token metadata rather than inventing it.
  • Runs always target the document's latest completed analysis. If you open an older analysis, the run still executes against the latest one and its citations will not resolve against the parse on screen.
  • Answers render as plain text. Models that emit markdown will show the markers literally.
  • Parsed nodes are read-only. Chunk text can still be corrected over the API (PATCH /api/documents/{id}/chunks/{id}) and on the legacy /studio surface when STUDIO_MODE_ENABLED=true, but the document workspace itself is preview-only in 0.7.0.

🔍 Release quality gate

Gated by the repo's 12-point audit (docs/audit/master.md). The six audits touched by the remediation (DRY, Decoupling, Security, Tests, Documentation, Performance) were re-run on release/0.7.0 after the remediation merge (PR #320, commit 94eec28); the other six carried their first-pass scores forward. Result: 0 CRITICAL, ≈88/100 overall.

What the remediation landed:

  • Decoupling (80 → 94): a public-barrel boundary between frontend features, enforced by an ESLint no-restricted-imports rule.
  • Security (0 MAJOR remaining): SSRF screening on the Ollama connection probe — link-local, cloud-metadata, reserved and unspecified addresses are rejected before any outbound request, while loopback and LAN stay allowed because that is where Ollama legitimately runs. Trust model documented in SECURITY.md.
  • Performance (76 → 86): two N+1 query patterns collapsed into single batched queries in StoreService.
  • Tests (93 → 100): the 413 oversized-upload guard is now covered. Note the checklist score includes an e2e item that was not re-executed for this gate.

Nine MAJOR findings remain — above the audit's own 3-MAJOR blocking threshold. They are accepted as documented, tracked debt for 0.7.x under the conditional-GO clause, not silently carried. See docs/audit/reports/release-0.7.0-reaudit/summary.md.

Full changelog: CHANGELOG.md · Compare: v0.6.2...v0.7.0

Assets 2
Loading