fix: guard against IndexError when LLM API returns empty choices list

[qizwiz]

Problem

Three places in markitdown call response.choices[0].message.content immediately after client.chat.completions.create(...) without checking whether choices is non-empty:

• packages/markitdown/src/markitdown/converters/_image_converter.py:138
• packages/markitdown/src/markitdown/converters/_llm_caption.py:50
• packages/markitdown-ocr/src/markitdown_ocr/_ocr_service.py:102

The OpenAI API (and OpenAI-compatible providers) can return an empty choices list in three documented scenarios:

1. Content filtering — when the image triggers a policy violation, the API returns finish_reason: "content_filter" with an empty choices list
2. Streaming edge cases — SSE stream closed before any choices are emitted
3. OpenAI-compatible providers — local LLMs, proxies, and alternative providers may return non-standard response shapes

In all three cases, choices[0] raises IndexError: list index out of range. This crash is silent in development (dev images don't hit content filters) and surfaces in production on real user content.

Formal verification

This was found via pact static analysis and formally verified with Z3 SMT:

Bug model (SAT): content_filtered=True → choices_len=0, access_index=0 → 0≥0 → IndexError
Fix model (UNSAT): With if not response.choices guard, access_attempted ∧ choices_len=0 is a contradiction — IndexError is unreachable on all trigger paths.

Fix

# _image_converter.py and _llm_caption.py
response = client.chat.completions.create(model=model, messages=messages)
if not response.choices:
    return None
return response.choices[0].message.content

# _ocr_service.py (inline — consistent with existing `text or ""` guard below)
text = response.choices[0].message.content if response.choices else None

The _ocr_service.py path already has a bare except Exception that returns OCRResult(text="") on failure, so the None propagates safely through the existing text.strip() if text else "" guard on the next line.

Prior art

This exact crash pattern appears in multiple open issues across the LLM ecosystem: plastic-labs/honcho#676, aden-hive/hive#4767, TheR1D/shell_gpt#741, langchain-community#475.

[qizwiz]

@microsoft-github-policy-service agree

[qizwiz]

Note: second crash vector discovered

Testing against live providers found that Gemini 2.5 Flash returns HTTP 200 with choices[0].message = None (not an empty choices list) when content is filtered — finish_reason: PROHIBITED_CONTENT. This causes AttributeError: 'NoneType' object has no attribute 'content' even when choices is non-empty.

If the files in this PR have if not response.choices: return style guards but then access .message.content unconditionally, they may still be vulnerable to this path. The comprehensive guard is:

if not response.choices or response.choices[0].message is None:
    return  # or handle appropriately

Happy to push an update if the current guards are incomplete.