V2 admin: Enhanced Extraction section with Content Understanding nested

[Paul Lizer (paullizer)]

Summary

In V2 Admin Settings, "Enable Enhanced extraction" sat inside a collapsed group of the Document Intelligence card. Azure AI Content Understanding, the engine behind Enhanced extraction, was a separate card with no visibility condition. Admins could configure Content Understanding while Enhanced was off, the one state in which it is never called, and nothing on the page tied the two together.

• One Enhanced Extraction section (Knowledge > Document Extraction). enhanced-extraction-section replaces content-understanding-section, and the Enhanced switch is its capability. Beneath the switch are the extraction mode, Auto sample pages, formula extraction, and the Content Understanding connection and analyzers, all hidden while it is off. Document Intelligence keeps only its connection settings.
• The section names the engine in force. With Enhanced on, a notice says whether documents will use Azure AI Content Understanding or Document Intelligence Layout, and why Layout: no endpoint, no key, or a cloud without Content Understanding. While that depends on unsaved edits, it says "Takes effect when you save". The Content Understanding connection group opens on its own while no endpoint is set.
• Fix: turning Enhanced on in V2 now takes effect. V2 left the extraction mode on Standard, so new uploads never used Enhanced and Content Understanding never ran. Turning the switch on now moves a Standard mode to Auto, as the classic page always has. This happens in the draft before saving, and on the server for saves that omit the mode. An explicit Standard choice is kept.
• Fix: runtime-flag gating. A new content_understanding_supported runtime flag hides Content Understanding in clouds that do not offer it, matching the classic page. SettingsSection now receives the runtime flags. Its own visibility filter used to run without them, so flag-gated fields, including the Inbound MCP settings, were dropped from the card even when the page meant to show them.

Screenshots

Enhanced Extraction section, captured from the built SPA with the UI test fixture (fixture data only)

Off: only the switch is shown, and its help text says what turning it on unlocks.

On, Content Understanding not connected: the mode has moved to Auto, the engine notice explains the Layout fallback, and the connection group is open.

On, Content Understanding connected: the engine notice confirms Content Understanding, and the connection folds away.

Notes for review

• Generic schema vocabulary, not special cases.
  • on_enable: {set, when} on a switch sets companion values when it is turned on. The browser applies it in applyEnableEffect, and the server in _apply_enable_defaults, with a field warning. Only an off-to-on transition counts, a companion named in the same save wins, and turning the switch back off before saving takes the companion back.
  • Group open_until_set: <key> opens an optional connection group while the capability is on and the key is blank.
  • Python evaluate_dependency now understands flag conditions. With no flags passed it treats them as met, like _dependency_is_satisfied.
• The status chip stays "Configured" on the Layout fallback. Content Understanding can't be required, because Enhanced works without it, so the engine notice nudges instead of a warning chip.
• Turning Enhanced off doesn't rewrite the stored mode to read, unlike the classic form. The effective mode is still Standard (get_effective_document_intelligence_pdf_image_extraction_mode), and turning Enhanced back on restores the previous choice.
• The Document Intelligence connection test sends the mode only while Enhanced is on, so with Enhanced off it tests Read, which is what documents then use.
• Classic page: it only gains id="enhanced-extraction-section" on its Enhanced switch row, so the shared ADMIN_NAV link resolves. It already nests Content Understanding under the switch.
• Deep links: V2 links to #content-understanding-section no longer match a card. docs/admin/knowledge.md keeps that anchor as a sub-heading.

Before merging: V2 merge and renumber

paullizer-react-v2-ui is 17 commits past this branch's base (1b8d4c47b) and at 0.261.264, so this change's 0.261.260 is already taken; the next free version today is 0.261.265. Merging conflicts in five files, and each conflict is additive, so keep both sides:

• application/single_app/config.py: VERSION.
• docs/explanation/release_notes.md: both add a section at the top.
• functional_tests/test_v2_admin_capability_placement.py: header version.
• functional_tests/test_v2_admin_section_logic.ts: a header line, one import on each side (buildFieldIndex / applyEnableEffect), and checks appended by both.
• application/v2_ui/src/components/admin/SettingsSection.tsx: c1573f1 added fieldsByKey as the fourth isFieldVisible argument on the line this branch extends with runtimeFlags. Combine them as isFieldVisible(field, settings, draft, fieldsByKey, runtimeFlags), with both in the memo dependencies. The new open_until_set reader can pass fieldsByKey to readSectionValue too.

The version also appears in the headers of the new and updated tests, in the new feature doc, and in the release notes heading.

Linked issue

N/A. No issue was opened for this change.

Release Notes & Latest Features

• New Feature
• Bug Fix
• UI Enhancement
• Breaking Change
• Internal only

Is this visible to end users?

• Yes
• No

Is this admin-facing (Admin Settings, governance, deployment, config)?

• Yes
• No

Should this become a Latest Feature card?

• Yes
• No
• Already added

Screenshot needed for the card?

• Yes
• No
• Attached

Version bump

• application/single_app/config.py VERSION third segment bumped, or not needed because this is docs-only (0.261.259 -> 0.261.260; renumber when merging V2, see above)
• deployers/version.txt bumped, or not needed because deployers/ was not changed (deployers/ not changed)

Testing / validation

All results below are for this branch on its base 1b8d4c47b. Rerun after the V2 merge.

• npm ci, npm run typecheck, npm run build (in application/v2_ui): passed
• python functional_tests/test_v2_admin_enhanced_extraction_section.py (new): 10/10 passed
• python functional_tests/test_v2_admin_knowledge_extraction.py: 9/9 passed
• python functional_tests/test_v2_admin_capability_placement.py: 7/7 passed
• python functional_tests/test_v2_admin_schema_vocabulary.py: 12/12 passed
• python functional_tests/test_v2_admin_section_shell.py: 5/5 passed, including all 39 TypeScript checks in test_v2_admin_section_logic.ts (9 new)
• python -m pytest -q functional_tests/test_v2_admin_enhanced_extraction_section.py functional_tests/test_v2_admin_knowledge_extraction.py functional_tests/test_v2_admin_capability_placement.py functional_tests/test_v2_admin_schema_vocabulary.py: 38 passed
• Related suites, each run as python functional_tests/<file>, all passed:
  • test_admin_settings_fields_registry_integrity.py 5/5
  • test_v2_admin_settings_normalization.py 15/15
  • test_v2_admin_inbound_mcp_parity.py 9/9
  • test_v2_admin_settings_layout.py 5/5
  • test_v2_admin_settings_secret_handling.py 6/6
  • test_v2_admin_settings_secret_redaction.py 4/4
  • test_v2_admin_knowledge_web_research.py 9/9
  • test_v2_admin_knowledge_audio_video.py 9/9
  • test_v2_admin_knowledge_file_sync.py 9/9
• python functional_tests/test_docs_app_surface_coverage.py: 7/7 passed
• python functional_tests/test_docs_site_quality.py: 6/6 passed
• Route policy tests in functional_tests/route_tests/ (there are no route changes): all passed
  • test_route_blueprint_policy_inventory.py 12/12
  • test_route_unauthenticated_policy_contract.py 7/7
  • test_route_policy_test_coverage.py 2/2
• python -m pytest -q ui_tests/test_v2_admin_enhanced_extraction_section.py ui_tests/test_v2_admin_agents_visual_hierarchy.py ui_tests/test_v2_admin_settings_wide_layout.py ui_tests/test_v2_admin_model_catalog_workbench.py ui_tests/test_v2_admin_version_status.py: 54 passed, 7 of them new. The new tests cover:
  • the off state
  • turning Enhanced on: Auto, the open connection, the live engine notice and the saved payload
  • turning it back off before saving
  • the connected summary
  • a cloud without Content Understanding
  • 390px and 1440px widths
• python scripts/check_xss_sinks.py --base-sha 1b8d4c47b --head-sha HEAD <11 changed application files>: passed
• These fail identically before and after this change; I verified each on base 1b8d4c47b:
  • test_v2_admin_settings_schema.py: 10/11 (m365_trusted_download_hosts default type)
  • test_content_understanding_extraction_engine.py: 18/19 (redacted-secret registration string)
  • test_admin_settings_nav_map.py: 3/4 (content-screening tab pane)
  • test_admin_settings_sidebar_card_parity.py: 3/4 (m365-retrieval-configuration card)
  • test_docs_release_notes_integrity.py: 0/1 (generated release-note pages are stale)
  • test_docs_link_integrity.py: 2/5 (the same 11 broken links as base)

Documentation

• Release notes updated, or not needed (v0.261.260 section, to be renumbered)
• Feature documentation updated, or not needed
  • New docs/explanation/features/V2_ENHANCED_EXTRACTION_ADMIN_SECTION.md
  • Updated docs/admin/knowledge.md, which keeps the #content-understanding-section anchor
  • Updated V2_ADMIN_KNOWLEDGE_SETTINGS.md and CONTENT_UNDERSTANDING_ENHANCED_EXTRACTION.md
  • Regenerated docs/_data/app_surface.yml
• Fix documentation updated, or not needed (the V2 Enhanced switch fix is described in the feature doc; no separate fix doc)

Security checklist

• New Flask routes include @swagger_route(security=get_auth_security()) (no new routes)
• Settings sent to non-admin frontends use sanitize_settings_for_user() (no new settings payloads; the only addition is a boolean runtime flag on the admin-only GET /api/v2/admin/settings)
• Browser JavaScript is served from local SimpleChat static assets only; no CDN-hosted JS
• No secrets, keys, connection strings, or local-only artifacts are included (the build output and UI test artifacts are git-ignored; the screenshots use fixture data)