[Pooria90]

Summary

Closes #1654.

One bad document no longer stops an ingest run. An undecodable file, a corrupt PDF, a failed download, or an error from the chunker or store is reported as a DocumentFailed event, and the rest of the corpus is still ingested.

• Loaders yield a LoadFailure (source, error) for a source they can't read, then continue with the next one. Every file-based and cloud loader isolates each source through a shared _isolate_source helper on BaseDocumentLoader.
• RetrievalRuntime turns each LoadFailure and each failing document into a DocumentFailed with a new stage field ("load", "chunk", "embed" or "store"). The new on_error="skip" | "raise" option defaults to "skip"; "raise" keeps the old behaviour.
• Always raised, in both modes: EmbeddingModelMismatchError, errors raised out of a loader's own stream (it can't resume), and exceptions from the on_ingest callback.

Type of change

• Bug fix
• Feature
• Breaking change
• Docs
• Refactor / chore / build / tests

Checklist

• Lint & format pass (ruff check . && ruff format .)
• Tests added/updated and pass locally (pytest tests)
• Docs updated if user-facing behavior changed
• Breaking changes include migration notes

Notes

Migration

• BaseDocumentLoader.astream() now yields Document | LoadFailure. Code that reads astream() directly should check for LoadFailure. load(), aload() and Chunker.astream_documents still raise the error.
• DocumentFailed has a new required stage field, and document_id is None when stage == "load".

Left out

• Inside a CSV or JSON file, one bad row or object fails the rest of that file.
• No circuit breaker yet: if the store is down, every remaining document is reported as failed.
• A store error partway through a document can still leave it half-written ([05] [Bug] [Retrieval] Partially-failed re-ingest deletes the prior good version of a document #1187).