[Chien Yuan Chang (chienyuanchang)]

Summary

• expose Document Intelligence model selection with docintel_model_id
• expose analysis add-ons with docintel_features; None preserves the existing defaults and [] disables all default add-ons
• expose queryFields with docintel_query_fields and automatically enable the required queryFields feature
• serialize structured fields from prebuilt and custom models as YAML front matter
• add matching CLI flags for model, features, and query fields
• retain the SDK-default API version behavior from fix(doc-intel): default api_version to None in DocumentIntelligenceConverter #2267 while adding MarkItDown user-agent telemetry
• document API-key, AZURE_API_KEY, and DefaultAzureCredential authentication

Consolidated work

• Closes FORMULAS feature is unconditionally set in Azure Document Intelligence converter #1536 and supersedes fix: remove FORMULAS from default Document Intelligence features (fixes #1536) #1975 with an explicit feature opt-out instead of replacing one fixed feature set with another.
• Closes Title: Expose model_id and analysis features as configurable parameters in DocumentIntelligenceConverter #2273 and incorporates the docintel_features contract and test cases from feat(doc-intel): expose model_id and analysis features on DocumentIntelligenceConverter (#2273) #2284.
• Closes Update Readme to include how to initialize Azure Document Intelligence correctly? #1446 and incorporates the focused API-key documentation from docs: add Azure Document Intelligence API-key example #1634.

Usage

from azure.ai.documentintelligence.models import DocumentAnalysisFeature
from markitdown import MarkItDown

md = MarkItDown(
    docintel_endpoint="<document_intelligence_endpoint>",
    docintel_model_id="prebuilt-layout",
    docintel_features=[
        DocumentAnalysisFeature.OCR_HIGH_RESOLUTION,
        DocumentAnalysisFeature.STYLE_FONT,
    ],
    docintel_query_fields=["Title", "Author"],
)
result = md.convert("document.pdf")
print(result.markdown)

Use docintel_features=[] to disable the default formulas, ocrHighResolution, and styleFont add-ons. Office inputs continue to omit OCR-only add-ons. Query fields automatically add the required queryFields feature without mutating the caller's feature list.

Validation

• GITHUB_ACTIONS=1 python -m pytest packages/markitdown/tests -q — 1080 passed, 57 skipped
• focused Document Intelligence and CLI tests — 54 passed
• Black 23.7.0 — 5 changed Python files unchanged
• git diff --check
• live Entra-authenticated Document Intelligence calls:
  • prebuilt-layout succeeded with default add-ons, no add-ons, and only ocrHighResolution
  • prebuilt-read succeeded with no add-ons and returned its expected flatter text-oriented Markdown
  • prebuilt-receipt succeeded with no add-ons and produced structured YAML front matter
  • the queryFields request path was accepted with valid identifiers, but the selected repository samples returned no query-field documents; positive field serialization remains covered by unit tests

Credits

• docintel_features design and tests adapted from feat(doc-intel): expose model_id and analysis features on DocumentIntelligenceConverter (#2273) #2284 by Tai An (@Anai-Guo).
• API-key documentation adapted from docs: add Azure Document Intelligence API-key example #1634 by 贺苏桓 (@hshgogogo).
• Formula-quality motivation from FORMULAS feature is unconditionally set in Azure Document Intelligence converter #1536 and fix: remove FORMULAS from default Document Intelligence features (fixes #1536) #1975 by hanhan761.

[Copilot]

🟡 Changes recommended

Structured output can produce invalid or incorrectly typed YAML and lose or misattribute fields from multiple documents.

2 open issues

• Quote YAML strings and keys that could be misinterpreted · New
• Preserve field mappings separately across multiple documents · New

What changed in this PR

This PR expands MarkItDown’s Azure Document Intelligence integration with configurable analysis options and structured output while preserving existing defaults.

Changes:

• Exposes model selection, analysis features, and query fields through Python and CLI options.
• Adds YAML front matter for extracted fields and MarkItDown user-agent telemetry.
• Documents authentication options and adds converter and CLI tests.

File	Description
README.md	Documents authentication, configuration, and structured output.
packages/​markitdown/​tests/​test_docintel_converter.py	Tests configuration, request forwarding, telemetry, and front matter.
packages/​markitdown/​tests/​test_cli_misc.py	Tests forwarding Document Intelligence CLI options.
packages/​markitdown/​src/​markitdown/​converters/​_doc_intel_converter.py	Implements configurable analysis and structured-field serialization.
packages/​markitdown/​src/​markitdown/​_markitdown.py	Forwards public configuration to the converter.
packages/​markitdown/​src/​markitdown/​__main__.py	Adds and parses Document Intelligence CLI flags.

_{Review effort: Balanced}

[Adam Fourney (afourney)]

This comment was auto-generated by GPT-6 Astra and posted at the repository maintainer’s request.

Rechecked commit fd3b526c641b11d9e24dd5040ad21fd58a67ebca. The YAML quoting change resolves the examples from the earlier review: all 18 string key/value round-trip checks and 50 focused Document Intelligence and CLI tests passed.

Two P2 findings remain:

1. Preserve document boundaries when serializing structured fields. _fields_to_front_matter() merges every document into one mapping. Later documents overwrite matching fields but retain unmatched fields from earlier documents. With two SDK AnalyzedDocument objects, I reproduced Vendor B’s name and invoice ID paired with Vendor A’s invoice total. This produces a record that never existed and discards earlier documents’ fields. Serialize each document’s fields separately and add coverage for overlapping and missing fields across documents. Code

2. Handle selection-group values before falling back to raw content. _field_value() does not handle value_selection_group. An SDK DocumentField(type="selectionGroup", value_selection_group=["Email"]) returns None and disappears from the front matter when content is absent. When raw content is present, the selected values are still lost in favor of that text. Preserve the selected-value list and add regression coverage. Code

I recommend addressing these before merging. Validation used local SDK objects and mocked service calls; the full suite and live Azure calls were not run.

[Copilot]

🔵 Needs a closer look

Structured fields containing control characters can produce invalid YAML front matter that downstream parsers reject.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Escape control characters in quoted YAML strings

packages/​markitdown/​src/​markitdown/​converters/​_doc_intel_converter.py:223

The quoted-string escaping leaves control characters such as form feed (U+000C) and backspace (U+0008) unchanged. For example, a structured field containing page one\fpage two produces a literal form feed inside the quoted scalar. YAML forbids that character even inside quotes, so downstream consumers cannot parse the front matter. Escape the remaining control characters and add a regression case for a field containing a form feed.

2 resolved since last review

• Preserve field mappings separately across multiple documents
• Quote YAML strings and keys that could be misinterpreted

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Scientific-notation floats can lose their numeric type when the generated front matter is parsed by YAML 1.1 readers.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Preserve numeric type for scientific-notation floats

packages/​markitdown/​src/​markitdown/​converters/​_doc_intel_converter.py:206

Scientific-notation floats lose their numeric type with YAML 1.1 readers such as yaml.safe_load, which the new round-trip tests use. For example, value_number=1e-7 is emitted as 1e-07 and loads as a string rather than a float; 1e20 has the same problem. Include a decimal point in exponential float mantissas (for example, 1.0e-07) and add numeric round-trip regressions for small and large values.

_{Review effort: Balanced}