Skip to content

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:31b on Ollama for legacy installs),
  • it can call :meth:HybridSearch.search over the corpus and — when the caller wires one — a web_search over 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_iterations tool 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.