Problem

UNSTRUCTURED_INCLUDE_DEBUG_METADATA = os.getenv("UNSTRUCTURED_INCLUDE_DEBUG_METADATA", False)

os.getenv always returns a string when the variable is set, and any non-empty string is truthy in Python — so setting the variable to explicitly disable debug metadata (UNSTRUCTURED_INCLUDE_DEBUG_METADATA=false or =0) actually enables it, the opposite of the operator's intent. Only leaving the variable completely unset gives the intended False.

The codebase already has a correct helper for exactly this pattern elsewhere:

# partition/utils/config.py
def _get_bool(self, var: str, default_value: bool) -> bool:
    if value := os.environ.get(var):
        return value.lower() in ("true", "1", "t")
    return default_value

Fix

Parse the raw env var value the same way ENVConfig._get_bool does: "true"/"1"/"t" (case-insensitive) is True, everything else (including unset) is False.

Testing

Added test_include_debug_metadata_parses_bool_string, parametrized over "true"/"1"/"t" (expect True) and "false"/"0"/"no" (expect False), reloading the constants module after monkeypatch.setenv to pick up the change. Confirmed it fails against the pre-fix code (e.g. assert 'false' is False — got the string 'false', not the bool) and passes after.

• pytest test_unstructured/partition/utils/test_config.py — 11/11 passed.
• ruff check/ruff format --check clean.
• Updated CHANGELOG.md and bumped __version__.py to 0.25.1 per the contributing checklist. Note: two other open PRs (fix: strip leading UTF-8 BOM before JSON content-shape detection #4397, fix: catch UnicodeDecodeError in _is_json to avoid crashing detect_filetype() #4398) from this same debut day independently propose the same 0.25.1 bump from the same 0.25.0 base — whichever merges first "claims" 0.25.1; the others (including this one, if it lands last) will need a quick rebase to the next patch version. Flagging so it's not a surprise at merge time.

AI disclosure

Developed with AI assistance (Claude Code), which located the boolean-parsing bug while auditing environment-variable handling across the codebase and noticed the existing correct pattern in ENVConfig._get_bool that this constant didn't follow. I reviewed the diff, independently reproduced the bug and the fix by executing both, and ran the tests/linters myself before opening this PR.