>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3610866. --> Reported by: [abhisekmazumdar](https://www.drupal.org/user/3557964) >>> <h2>Problem/Motivation</h2> <p><em>Updated after the ai_agents migration (<span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/ai_answers/issues/3610874" title="Status: Closed (fixed)">#3610874: Plan the migration off the AI Assistant API to Agents and Tools</a></span>): the original summary referenced <code>retrieve()</code>, <code>collectSources()</code>, and <code>RERANK_CANDIDATE_MULTIPLIER</code>, which no longer exist. The case for the processor is stronger now, not weaker.</em></p> <p>Since the migration, ai_answers no longer issues the retrieval query at all. The agent's <code>ai_search:rag_search</code> tool runs it (<code>RagTool.php</code>: a plain Search API index query in chunk mode, limited by the tool's <code>amount</code> usage limit, filtered by <code>min_score</code> against <code>getScore()</code>). ai_answers only sees the tool's structured results afterwards, via <code>AnswerToolResultSubscriber</code>.</p> <p>The in-module rerank survived the migration as <code>AnswerService::maybeRerank()</code> / <code>rerankAvailable()</code> / <code>rerankSources()</code>, applied to those captured tool results. In the new architecture this has two problems the old code didn't have:</p> <ol> <li><strong>Ordering double-exposure.</strong> The rerank runs <em>after</em> the agent's LLM has already received the raw tool output in its original order (standard function calling: tool results go back into the conversation). The numbered sources block ai_answers injects into the next round's system prompt uses the <em>reranked</em> order. So the same chunks appear twice in the context window, in two different orders, and the citation numbering follows one while the model may anchor on the other.</li> <li><strong>The rerank pool collapsed.</strong> The old code over-fetched 4&times; the reference cap and reranked the wide pool. Now the pool is exactly the tool's <code>amount</code> results, and the entity cap trims to that same number, so reranking merely reorders the final set. Most of its value is gone.</li> </ol> <p>AI core 1.5.x ships a generic Search API processor that reranks any index query: <a href="https://git.drupalcode.org/project/ai/-/work_items/3586543">https://git.drupalcode.org/project/ai/-/work_items/3586543</a>, merged as ai MR <a href="https://git.drupalcode.org/project/ai/-/merge_requests/1729">https://git.drupalcode.org/project/ai/-/merge_requests/1729</a>. Enabling <code>ai_reranker</code> on the RAG index reranks the query <em>the tool itself issues</em>, before the agent's LLM ever sees the results. One order everywhere: tool response, sources block, references. ai_answers, ai_search, and ai_agents need no code changes for the reranking itself. It also composes with non-vector backends (Database, Solr) for free, which the in-module version never will.</p> <h2>Proposed resolution</h2> <p>Adopt the processor once drupal/ai ^1.5 is required. Delete <code>maybeRerank()</code>, <code>rerankAvailable()</code>, and <code>rerankSources()</code> from <code>AnswerService</code>; the module is pre-release, so no transition guard against double-reranking is needed, just an atomic switch.</p> <p>Four things need resolving before or during the migration, restated for the current architecture:</p> <ol> <li><strong>Chunk vs. entity granularity (unchanged, still blocking).</strong> The tool queries in chunk mode, so the retrieval unit is a chunk carried in <code>extraData('content')</code>, not an indexed field. <code>AiReranker::extractItemText()</code> only reads configured indexed source fields, so every chunk of one entity reranks as the same document. The companion patch against drupal/ai still applies: prefer <code>$item-&gt;getExtraData('content')</code> when present, fall back to the configured fields for whole-entity backends. Without it the migration regresses chunk-mode rerank quality. To be filed separately against the ai queue.</li> <li><strong>Score-threshold scale (moved out of our code).</strong> The filter is now the tool's <code>min_score</code> usage limit on the agent, plus the same-scale gate in <code>AnswerService::sourcesFromToolResults()</code>. With the processor active, <code>getScore()</code> returns rerank relevance instead of cosine similarity, so existing <code>min_score</code> values filter on the wrong scale. This becomes a documentation/recalibration note for site builders rather than a code change here.</li> <li><strong>Over-fetch and the reference cap are now one decision.</strong> The tool's <code>amount</code> limit is both the fetch size and (via the entity cap) the number of references shown, so widening the fetch for rerank quality currently also floods the reference list. Add a "maximum references" setting to the AI Answers per-agent settings so <code>amount</code> can be set wide (the rerank pool) while the display stays capped. <code>applyEntityCap()</code> already does the trimming; it just needs its own number.</li> <li><strong>Requirement bump.</strong> composer.json to <code>drupal/ai: ^1.5</code>. Until 1.5.x is stable the in-module rerank stays as the stopgap (per #2).</li> </ol> <h2>Remaining tasks</h2> <ul> <li>File the companion <code>AiReranker::extractItemText()</code> chunk-text patch against drupal/ai.</li> <li>Wait for drupal/ai 1.5.x stable; bump composer.json to <code>^1.5</code>.</li> <li>Remove <code>maybeRerank()</code>, <code>rerankAvailable()</code>, <code>rerankSources()</code> from AnswerService.</li> <li>Add the "maximum references" per-agent setting and point <code>applyEntityCap()</code> at it.</li> <li>Document the <code>min_score</code> recalibration for indexes with <code>ai_reranker</code> enabled.</li> <li>Add a regression test covering reranked results against a chunk-mode index.</li> </ul> <h2>User interface changes</h2> <p>One new field on the per-agent AI Answers settings form: maximum references shown.</p> <h2>API changes</h2> <p><code>AnswerService</code>'s rerank-related protected methods are removed.</p> <h2>Data model changes</h2> <p>One new key in the <code>ai_answers.agent_settings</code> config schema for the reference cap.</p>