[roydonsequeira]

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: LlamaIndexRetrieval and FilesRetrieval block the event loop on every lookup #7674

Problem:
LlamaIndexRetrieval.run_async called the retriever's synchronous retrieve() on the event loop. Retrieval blocks on I/O: a VectorStoreIndex retriever embeds the query before it searches, and FilesRetrieval's default GoogleGenAIEmbedding does that with a synchronous request. Every other task on the loop waited for the lookup, and when the model asked for several lookups in one turn, the parallel calls ran one after another.

Solution:
Run retrieve in a worker thread with asyncio.to_thread, as VertexAiRagRetrieval did for #5033. FilesRetrieval inherits the change. Switching to aretrieve would not be enough: BaseRetriever only requires _retrieve, and its default _aretrieve falls back to it, so retrievers without an async path of their own, such as SummaryIndexEmbeddingRetriever, SQLRetriever and AutoMergingRetriever in llama-index-core, would still block the loop.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

test_run_async_keeps_the_event_loop_free_while_retrieving in tests/unittests/tools/retrieval/test_llama_index_retrieval.py uses a retriever that blocks until another task on the loop releases it. On main it fails with TimeoutError: retrieve blocked the event loop; with the fix it passes. The existing tests are unchanged.

$ pytest tests/unittests/tools/retrieval
32 passed, 5 warnings in 27.35s

Full suite on Windows 11, Python 3.11 (pytest tests/unittests -n 4): 71 failed, 20783 passed, 107 skipped. Every one of the 71 also fails on unmodified main in this environment, and none of them is in tools/retrieval/.

Manual End-to-End (E2E) Tests:

An Agent with a LlamaIndexRetrieval over a VectorStoreIndex whose embedding model takes one second per query, run through InMemoryRunner. A scripted model stands in for Gemini and asks for two lookups in one turn, so the run needs no API key, and a 10 ms heartbeat task measures the longest event-loop stall.

# main
run_async: took 1.01s, event loop stalled for 1.01s
Runner turn with two parallel search_docs calls: took 2.14s, event loop stalled for 2.01s

# this change
run_async: took 1.00s, event loop stalled for 0.02s
Runner turn with two parallel search_docs calls: took 1.11s, event loop stalled for 0.10s

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

The formatters, linters and repository checks from .pre-commit-config.yaml pass on both files, and mypy reports no errors in llama_index_retrieval.py.