Make the default silent-chunk-drop on parse errors discoverable

[ojassharma7]

Description

extract()'s default (suppress_parse_errors=True) drops a chunk on a parse or schema error with no exception raised — the chunk's data is simply missing from the result. This is easy to miss: any caller-side retry logic written around catching a parse exception from extract() never fires, because the exception never reaches it.

Traced and reported by @reichaves on #358, after independently hitting it in reichaves/langextract-fundos — not a bug, an existing knob (resolver_params={'suppress_parse_errors': False}) that just wasn't visible enough. No behavior change — only visibility of the existing default, per that comment: "Might be worth a doc callout or a debug-level log distinguishing 'chunk silently dropped, no retry possible' from other warnings."

• resolver.py: both warnings explicitly say the chunk was omitted, identify the parsing or schema error, and show the existing resolver_params={'suppress_parse_errors': False} option for raising an exception.
• extraction.py: extract()'s docstring gets a Note: callout right after the summary — ahead of the full Args list — instead of the behavior being reachable only via one line buried under resolver_params.

Related to #358

Type: Documentation (log-message wording + docstring only; no behavior change).

How Has This Been Tested?

• Regression tests verify that both parsing and schema warnings identify the omitted chunk and show the complete opt-out setting.
• Focused tests: python -m pytest tests/resolver_test.py tests/annotation_test.py tests/init_test.py — 146 passed.
• Formatting, source lint, and test lint passed.
• PR CI passed, including Python 3.10/3.11/3.12 and Ollama/plugin integration tests.
• Secure fork CI verified and merged head ea2094518f32ad9779e199ecc3cfc91fce2353d4 onto current main: 12 live API tests passed; 3 credential-dependent or opt-in tests skipped.

Checklist:

• I have read and acknowledged Google's Open Source Code of conduct.
• I have read the Contributing page and am covered by the Google Individual CLA (signed for Forward Gemini generation settings #509).
• I have discussed my proposed solution with code owners in the linked issue(s) and we have agreed upon the general approach. — this is @reichaves's own suggested fix, verbatim from the comment on Challenges extracting structured data from large Brazilian fund regulation PDFs (230K+ chars, 22 entity types) #358.
• I have made any needed documentation changes (the Note: callout is the fix).
• I have added tests covering the changes.
• I have followed Google's Python Style Guide and ran pylint over the affected code.

[github-actions]

⚠️ Branch Update Required

Your branch is 1 commits behind main. Please update your branch to ensure CI checks run with the latest code:

git fetch origin main
git merge origin/main
git push

Note: Enable "Allow edits by maintainers" to allow automatic updates.

[reichaves]

Reporter of #358 here — this wording change addresses exactly what bit me, and I want to add the field numbers behind that report since they may be useful for review.

The document was a Brazilian FIDC fund regulation (a CVM regulatory filing, ~160K chars of PDF text reduced to ~50K before extraction). I split ~22 entity types across three extract() calls to keep each JSON response short enough to avoid truncation, and each call had a retry chain that halved max_char_buffer on a parse error: 3000 → 1500 → 1000.

That chain never once fired. Every parse failure was suppressed by the default, so the except block had nothing to catch — the run "succeeded" with chunks quietly missing. After switching to resolver_params={'suppress_parse_errors': False}, the same document on the same model went from 51 to 64 extracted entities. Nothing was wrong with the retry logic; it simply never ran.

What made this hard to spot is that the failure is silent in both directions: no exception, and the "Skipping chunk" warning reads like a routine skip rather than data loss with no recourse. The new message saying the data is gone and naming the opt-out would have saved me the debugging session.

One small note in favor of the docstring Note: as written: I had originally detected these failures by matching substrings of the exception message ("Failed to parse JSON", "Unterminated string", and so on). That was fragile, and this PR is a good illustration of why — it rewrites those strings. I have since moved to catching ResolverParsingError by type, which the Note: names explicitly. Keeping that type in the callout is worth more than it might look: it points callers at the stable contract instead of the message text.

No changes requested from me.

[github-actions]

⚠️ Branch Update Required

Your branch is 4 commits behind main. Please update your branch to ensure CI checks run with the latest code:

git fetch origin main
git merge origin/main
git push

Note: Enable "Allow edits by maintainers" to allow automatic updates.