research_loop
diapason.agents.research_loop
¶
Agentic research loop over the hybrid-search tool.
A small, self-contained planner-executor loop:
- the planner is supplied by the caller (the web endpoint resolves it from
config, falling back to
gemma4:31bon Ollama for legacy installs), - it can call :meth:
HybridSearch.searchover the corpus and — when the caller wires one — aweb_searchover the public web (22 Sept 2026: « Fais-moi une recherche [sur] des sites web qui proposent des jeux de programmation » under Deep Research got « your corpus has nothing », then a list from the model's memory with an invented site; the follow-up « Donne-moi les liens de ces sites » got links pulled from the user's e-mails — the request was stateless and web-less), - it receives the previous turns of the conversation (
history) so a follow-up like « ces sites » has a referent, - it gets up to
max_iterationstool calls, - tool results are trimmed before re-entering the context window, and
- the final reply must cite specific hits.
The loop is deliberately decoupled from the rest of the agent scaffolding
(ToolUsingAgent, EventBus, AgentContext, etc.) so the surface stays
small. Anything that wants tracing or registry integration can wrap it.
ResearchAgent
¶
Planner + executor loop over a single hybrid-search tool.
Parameters¶
engine:
An InferenceEngine that supports OpenAI-style tools in
generate (Ollama with a tool-capable model).
search:
The HybridSearch instance the planner can call.
model:
Planner model tag (default gemma4:31b).
max_iterations:
Hard ceiling on tool calls before the loop is forced into synthesis.
temperature, max_tokens, num_ctx:
Generation parameters passed through to engine.generate.
web_search:
Optional (query, recency, news) -> [WebHit]. When given, the
planner gets a web_search tool next to the corpus search.
on_event:
Optional callback fired at loop milestones so callers (e.g. the SSE
research router) can stream progress without rewriting the loop.
Receives a dict in one of these shapes:
- {"type": "search_call", "arguments": {...}} — about to call search
- {"type": "search_result", "num_hits": N, "top_titles": [...], "sources": [{"ref": 1, "title": ..., "sender": ..., "date": ..., "source_id": ..., "url": ...}, ...]} — search returned
- {"type": "clarify_call", "question": "..."} — about to ask for clarification
- {"type": "clarify_response", "response": "..."} — clarification received
- {"type": "final_answer", "text": "..."} — synthesis ready
The callback runs on the same thread as run and must be non-blocking.
run(query, *, history=None, hints=None)
¶
Run the loop end-to-end and return the synthesis plus a trace.
history — the previous user/assistant turns, placed before the
query so a follow-up has its referent. hints — system lines the
caller established about THIS query (what « ces sites » refers to,
that the user asked for the web), placed right after it.
ToolInvocation
dataclass
¶
One tool call together with what the planner asked for and got.
tool_name is "search", "web_search" or "clarify". For
search calls, num_results, top_titles and raw_hits are
populated (web_hits for the web); for clarify calls, response
holds the user's answer.
WebHit
dataclass
¶
One public-web result, as the router's web_search callable returns it.
build_sources_for_client(hits, *, total_cap=20, ref_offset=0)
¶
Produce the citation-friendly sources list streamed to the frontend.
One entry per hit, in the same order the planner sees them — so a
[N] citation in the synthesis maps to sources[N - 1] on the
client. We don't deduplicate by document_id: separate chunks of the
same email each get their own citation slot since the planner may quote
different parts.
build_web_sources_for_client(hits, *, ref_offset=0, total_cap=10)
¶
Same shape as :func:build_sources_for_client; source is web
and sender the site, so the client renders a web hit like any other.
renumber_citations(text, ref_to_source)
¶
Renumber [N] citations in text by first-appearance order.
The planner sees globally-offset refs across multiple search calls
(search 1 returns 1..20, search 2 returns 21..40, …). When the
synthesis arrives, the first ref the model actually cited becomes
[1], the second unique one becomes [2], and so on. Repeats
map to the same new ref. Refs the synthesis never cites are dropped
from the returned sources list — only the ones the user can
actually click on get carried through.
Parameters¶
text:
Synthesis text containing inline [N] references.
ref_to_source:
Mapping from the original (offset) ref to the source dict that
build_sources_for_client produced for that hit.
Returns¶
(new_text, ordered_sources)
new_text has every cited [N] rewritten to its new
sequence number. ordered_sources is the deduped list of
source dicts in the order they appear in the synthesis, each
with its ref field set to the new sequence number.
shape_results_for_model(hits, *, detailed_top=5, thread_ctx_per_hit=3, total_cap=20, ref_offset=0)
¶
Compact a hit list into a JSON payload the planner can chew through.
The first detailed_top rows keep their content snippet and trimmed
thread context; the remainder are summarised to title + sender + date so
the planner still sees the breadth of what's available without blowing the
context window. Each hit gets a numeric ref (1-indexed, plus
ref_offset) so the synthesis can cite it as [N]. The offset lets
multi-search runs hand the planner globally unique refs across calls so
a later renumbering pass can dedupe by first appearance.