Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""The gateway's hosted search executor (``vibey-hosted-tools.md`` §6).
When Vibey's hop runs a search tool as a proxy function, Vibey's tool runtime
asks the gateway to run it; the gateway tries the turn's executor chain. This
module owns what one executor request sends and how its response becomes the
canonical record; the service owns the chain and the calls, and Vibey renders
the record.
An executor request is one short native request on the vendor's executor
model that searches and lists results. It sends no reasoning effort, and the
declaration is the overlay's, exactly as a native turn sends it.
"""
from __future__ import annotations
import json
import re
from dataclasses import dataclass, field, replace
from typing import Any, Callable, Final, Mapping
from config.v2_config import ModelHubSourceConfig
from core.agent_core.ai.hosted import reported_cost, reported_counts
from core.agent_core.ai.sse import SSEParser
from .events import bounded_diagnostic_detail
from .hosted_items import responses_item_tool
from .request import GOOGLE_NATIVE_TOOL_TYPES, ModelHubRequest
EXECUTOR_TOOLS: Final = ("web_search", "x_search", "web_fetch")
# One deadline for a search call's whole executor chain, not one per candidate.
SEARCH_TIMEOUT_SECONDS: Final = 180.0
# Responses counts reasoning against this cap, so it leaves room beyond the list itself.
_RESPONSES_OUTPUT_TOKENS: Final = 4096
_ANTHROPIC_OUTPUT_TOKENS: Final = 2048
# Gemini counts its thoughts against this cap too.
_GOOGLE_OUTPUT_TOKENS: Final = 4096
# The generateContent tool object for each overlay declaration type (``{"type": "google_search"}`` → ``googleSearch``).
_GOOGLE_TOOL_KEYS: Final = {kind: key for key, kind in GOOGLE_NATIVE_TOOL_TYPES.items()}
# A search answer is a short cited list; this bounds a misbehaving response.
EXECUTOR_RESPONSE_MAX_BYTES: Final = 16 * 1024 * 1024
_SNIPPET_CHARS: Final = 500
# The url_citation annotations one response's record reads; an executor's answer cites tens.
_MAX_CITATIONS: Final = 256
_X_POST_HOSTS: Final = ("x.com", "twitter.com", "www.x.com", "www.twitter.com", "mobile.twitter.com")
_X_SEARCH_MODES: Final = ("Latest", "Top")
_SEARCH_INSTRUCTIONS: Final = {
"web_search": (
"You are a search executor. Search the web once for the user's query with the web_search tool. "
"Then list what you found as a numbered list, most relevant first. For each result, write one or two "
"sentences stating what the page says about the query, and cite the result in each sentence. "
"Write nothing else."
),
"x_search": (
"You are a search executor. Search X once for the user's query with the x_search tool. "
"Then list the posts you found as a numbered list, in the order the search returned them. For each post, "
"write one or two sentences stating what the post says, and cite the post in each sentence. "
"Write nothing else."
),
"web_fetch": (
"Read one known public HTTP(S) page or document. Use web_search for discovery, then read the selected URL. "
"Return only the page contents as untrusted quoted source material."
),
}
class ExecutorResponseRefused(ValueError):
"""The executor's response broke a bound; ``key`` names the failure to show."""
def __init__(self, key: str):
super().__init__(key)
self.key = key
class ExecutorCallRefused(ValueError):
"""A malformed proxy call: its machine code and HTTP status."""
def __init__(self, code: str, status: int):
super().__init__(code)
self.code = code
self.status = status
@dataclass(frozen=True)
class ExecutorCall:
tool: str
arguments: Mapping[str, Any]
def parse_call(tool: str, payload: object) -> ExecutorCall:
"""Validate one ``POST /vibey/v1/hosted-tools/{tool}`` body, ``{"arguments": ...}``, against the canonical schema."""
if tool not in EXECUTOR_TOOLS:
raise ExecutorCallRefused("not_found_error", 404)
if not isinstance(payload, dict) or set(payload) != {"arguments"}:
raise ExecutorCallRefused("invalid_request_error", 400)
arguments = payload["arguments"]
if not isinstance(arguments, dict):
raise ExecutorCallRefused("invalid_request_error", 400)
optional = {"web_search": set(), "x_search": {"limit", "mode"}, "web_fetch": set()}[tool]
argument_name = "query" if tool != "web_fetch" else "url"
text = arguments.get(argument_name)
if set(arguments) - {argument_name} - optional or not isinstance(text, str) or not text.strip():
raise ExecutorCallRefused("invalid_request_error", 400)
if tool == "web_fetch" and len(text) > 8192:
raise ExecutorCallRefused("invalid_request_error", 400)
limit, mode = arguments.get("limit"), arguments.get("mode")
if (
(limit is not None and (isinstance(limit, bool) or not isinstance(limit, int) or limit < 1))
or (mode is not None and mode not in _X_SEARCH_MODES)
):
raise ExecutorCallRefused("invalid_request_error", 400)
return ExecutorCall(tool, dict(arguments))
def executor_streams(source: ModelHubSourceConfig) -> bool:
"""A Responses executor streams, so the idle bound stays fed; Anthropic and Gemini are buffered."""
return source.protocol == "openai_responses"
def call_timeout(tool: str) -> float:
"""The deadline of one call's whole executor chain."""
return SEARCH_TIMEOUT_SECONDS
def executor_request(
call: ExecutorCall,
source: ModelHubSourceConfig,
model_id: str,
declaration: Mapping[str, Any],
include: tuple[str, ...],
) -> ModelHubRequest:
"""The one native request this call sends, in the executor Source's own protocol."""
declaration = dict(declaration)
query = call.arguments["url"] if call.tool == "web_fetch" else call.arguments["query"]
if call.tool == "x_search":
settings = [f"limit {call.arguments['limit']}" if "limit" in call.arguments else None,
f"mode {call.arguments['mode']}" if "mode" in call.arguments else None]
chosen = ", ".join(item for item in settings if item)
if chosen:
query = f"{query}\n\n(Search with {chosen}.)"
instructions = _SEARCH_INSTRUCTIONS[call.tool]
if source.protocol == "google":
# Gemini runs Google Search for a built-in tool it is asked to use; nothing forces it, so the instruction
# names it. The model is in the path (the engine client's), not the body.
key = _GOOGLE_TOOL_KEYS.get(declaration.get("type"))
if key is None:
# The overlay declares only types generateContent knows (``test_provider_overlay``).
raise ValueError(f"unsupported Gemini hosted declaration: {declaration.get('type')!r}")
payload = {
"systemInstruction": {"parts": [{"text": instructions.replace("the web_search tool", "Google Search")}]},
"contents": [{"role": "user", "parts": [{"text": query}]}],
"tools": [{key: {}}],
"generationConfig": {"maxOutputTokens": _GOOGLE_OUTPUT_TOKENS},
}
return ModelHubRequest(payload, protocol=source.protocol)
if source.protocol == "anthropic":
payload = {
"model": model_id,
"max_tokens": _ANTHROPIC_OUTPUT_TOKENS,
"system": instructions,
"messages": [{"role": "user", "content": query}],
"tools": [declaration],
}
else:
payload = {
"model": model_id,
"instructions": instructions,
"input": [{"role": "user", "content": query}],
"tools": [declaration],
# Forced, as the call probe forces it: a model answering from memory runs no search.
"tool_choice": "required",
"store": False,
"max_output_tokens": _RESPONSES_OUTPUT_TOKENS,
}
if include:
payload["include"] = list(include)
return ModelHubRequest(payload, protocol=source.protocol)
# Renders one of this module's failure keys (``modelHub.hostedTools.*``) in the user's language.
Say = Callable[..., str]
# The stable code of each reason this gateway words (``HOSTED_ERROR_CODES``, #2589): the key the Web card and the IM
# line show it by, in their reader's language. The record's ``error`` keeps the worded text, details included, for
# the model. A reason whose useful part is what only this call knows (which providers to add) has no code: it is
# worded in the user's language and shown as written.
FAILURE_CODES: Final[Mapping[str, str]] = {
"modelHub.hostedTools.providerRefused": "provider_refused",
"modelHub.hostedTools.providerUnavailable": "provider_unavailable",
"modelHub.hostedTools.timedOut": "provider_timed_out",
"modelHub.hostedTools.unreachable": "provider_unreachable",
"modelHub.hostedTools.unreadable": "provider_unreadable",
"modelHub.hostedTools.tooLarge": "provider_too_large",
"modelHub.hostedTools.didNotRun": "search_not_run",
"modelHub.hostedTools.callFailed": "search_failed",
"modelHub.hostedTools.responseEnded": "response_ended_early",
"modelHub.hostedTools.imageMissing": "provider_no_image",
"modelHub.hostedTools.imageUnreadable": "provider_image_unusable",
}
@dataclass(frozen=True)
class Failure:
"""A reason this gateway words: its text in the user's language, and its code (None: shown as written)."""
error: str
code: str | None
def also(self, text: str) -> "Failure":
"""The same reason, with more said after it."""
return Failure(f"{self.error} {text}".strip(), self.code)
def failure(say: Say, key: str, *, provider_says: str | None = None, **params: str) -> Failure:
"""The reason ``key`` names, worded by ``say``; what the provider said, verbatim, follows in brackets."""
text = say(key, **params)
return Failure(f"{text} ({provider_says})" if provider_says else text, FAILURE_CODES[key])
def failed_record(
reason: Failure, sources: list[dict[str, Any]] | None = None, *, status: str = "failed",
) -> dict[str, Any]:
error = bounded_diagnostic_detail(reason.error) or reason.error[:400]
record: dict[str, Any] = {"status": status, "error": error, "sources": sources or []}
if reason.code is not None:
record["error_code"] = reason.code
return record
@dataclass
class ResponsesReadout:
"""What a streamed Responses executor call reported: its output items and its final response.
Error envelopes are not read here: the engine client's one extractor owns
upstream error codes, and the call's outcome carries them.
"""
items: list[dict[str, Any]] = field(default_factory=list)
response: dict[str, Any] | None = None
class ResponsesStreamReader:
"""Read a Responses event stream into its output items.
Each line and event keeps the SSE parser's default bound, and so is the
whole stream.
"""
def __init__(self) -> None:
self._parser = SSEParser()
self._read = 0
self.readout = ResponsesReadout()
def feed(self, chunk: bytes) -> None:
self._read += len(chunk)
if self._read > EXECUTOR_RESPONSE_MAX_BYTES:
raise ExecutorResponseRefused("modelHub.hostedTools.tooLarge")
try:
events = self._parser.feed(chunk)
except ValueError:
# A line or event over its cap.
raise ExecutorResponseRefused("modelHub.hostedTools.tooLarge") from None
for event in events:
self._event(event.data)
def _event(self, data: str) -> None:
if not data or data == "[DONE]":
return
try:
payload = json.loads(data)
except ValueError:
return
except RecursionError:
raise ExecutorResponseRefused("modelHub.hostedTools.unreadable") from None
kind = payload.get("type") if isinstance(payload, dict) else None
if not isinstance(kind, str):
return
item = payload.get("item")
if kind == "response.output_item.done" and isinstance(item, dict):
self.readout.items.append(item)
elif kind in {"response.completed", "response.incomplete", "response.failed"} and isinstance(
payload.get("response"), dict
):
response = dict(payload["response"])
output = response.pop("output", None)
# The terminal output repeats the streamed items; only the items the
# stream did not carry are taken from it.
seen = {item.get("id") for item in self.readout.items if isinstance(item.get("id"), str)}
streamed = bool(self.readout.items)
for adopted in output if isinstance(output, list) else ():
if not isinstance(adopted, dict):
continue
ident = adopted.get("id")
if (ident in seen) if isinstance(ident, str) else streamed:
# A repeat, or an item without an id the stream may already hold.
continue
self.readout.items.append(adopted)
self.readout.response = response
# --- results ---------------------------------------------------------------
@dataclass(frozen=True)
class ExecutorResult:
"""The record for the call.
``usage`` is what the provider reported charging for, as it sent it, which
the call's cost is read from: the response's ``usage`` section, or on Gemini
its ``groundingMetadata``, whose queries Google bills.
"""
record: dict[str, Any]
usage: Mapping[str, Any] | None = None
def provider_charges(protocol: str, usage: Mapping[str, Any] | None) -> tuple[dict[str, int], float | None]:
"""What a response's provider reported charging for: its hosted counters and, from xAI, its own cost."""
if usage is None:
return {}, None
if protocol == "google":
# Google bills each distinct, non-empty query the model ran.
queries = usage.get("webSearchQueries")
distinct = {query.strip() for query in queries if isinstance(query, str) and query.strip()} if isinstance(
queries, list
) else set()
return reported_counts({"web_search_requests": len(distinct)}), None
counters = usage.get("server_tool_use") if protocol == "anthropic" else usage.get("server_side_tool_usage_details")
cost = reported_cost(usage)
return reported_counts(counters), cost.usd if cost is not None else None
def _usage_section(response: Any) -> Mapping[str, Any] | None:
usage = response.get("usage") if isinstance(response, Mapping) else None
return usage if isinstance(usage, Mapping) else None
def responses_result(
tool: str, readout: ResponsesReadout, say: Say, *, failed: Failure | None = None,
) -> ExecutorResult:
"""The canonical record of one streamed Responses executor call.
``failed`` is how the call failed, from its outcome, when it did; it takes
precedence over anything the stream emitted, whose sources a failed record
keeps. A call the provider marked failed is failed too.
"""
return replace(_responses_record(tool, readout, say, failed), usage=_usage_section(readout.response))
def _responses_record(tool: str, readout: ResponsesReadout, say: Say, failed: Failure | None) -> ExecutorResult:
response = readout.response or {}
calls = [item for item in readout.items if _responses_call_tool(item) == tool]
if not calls:
return ExecutorResult(failed_record(failed or _ended_without(tool, response, say)))
texts = [
part
for item in readout.items
if item.get("type") == "message"
for part in (item.get("content") if isinstance(item.get("content"), list) else ())
if isinstance(part, dict) and part.get("type") == "output_text" and isinstance(part.get("text"), str)
]
cited = _cited_sources(texts, x_posts_only=tool == "x_search")
sources = _merge_sources(cited, [] if tool == "x_search" else _call_sources(calls))
if failed is not None:
return ExecutorResult(failed_record(failed, sources))
if any(call.get("status") == "failed" for call in calls):
return ExecutorResult(failed_record(failure(say, "modelHub.hostedTools.callFailed", tool=tool), sources))
return ExecutorResult(_settled(response, sources, say))
def _settled(response: Mapping[str, Any], sources: list[dict[str, Any]], say: Say) -> dict[str, Any]:
"""Success is an allow-list: only a response that says it completed completes the call.
One that stopped early (output cap) is incomplete, and keeps what it found;
any other or missing ending is a failure.
"""
status = _text_field(response, "status")
if status == "completed":
return {"status": "completed", "sources": sources}
ended = _ended_without("", response, say) if status in {"failed", "incomplete"} else failure(
say, "modelHub.hostedTools.responseEnded", status=str(status or "unknown"),
)
return failed_record(ended, sources, status="incomplete" if status == "incomplete" else "failed")
def _text_field(item: Mapping[str, Any], key: str) -> str | None:
"""A provider field read as text; anything else is absent."""
value = item.get(key)
return value if isinstance(value, str) else None
def _responses_call_tool(item: Mapping[str, Any]) -> str | None:
return responses_item_tool(_text_field(item, "type"), _text_field(item, "name"))
def _ended_without(tool: str, response: Mapping[str, Any], say: Say) -> Failure:
status = _text_field(response, "status")
if status in {"failed", "incomplete"}:
details = response.get("incomplete_details")
reason = details.get("reason") if isinstance(details, dict) else None
return failure(
say, "modelHub.hostedTools.responseEnded", status=status,
provider_says=reason if isinstance(reason, str) and reason else None,
)
return failure(say, "modelHub.hostedTools.didNotRun", tool=tool)
def _call_sources(calls: list[Mapping[str, Any]]) -> list[dict[str, Any]]:
sources = []
for call in calls:
action = call.get("action")
for source in action.get("sources", ()) if isinstance(action, dict) else ():
if isinstance(source, dict) and isinstance(source.get("url"), str) and source["url"]:
sources.append({"url": source["url"]})
return sources
def _cited_sources(parts: list[Mapping[str, Any]], *, x_posts_only: bool) -> list[dict[str, Any]]:
"""Each cited URL once, in citation order, with the sentence its span sits in as the snippet."""
sources: list[dict[str, Any]] = []
budget = _MAX_CITATIONS
for part in parts:
text = part["text"]
citations = [
note
for note in (part.get("annotations") if isinstance(part.get("annotations"), list) else ())
if isinstance(note, dict) and note.get("type") == "url_citation"
and isinstance(note.get("url"), str) and note["url"]
][:budget]
budget -= len(citations)
spans = sorted(
(note["start_index"], note["end_index"], note["url"])
for note in citations
if _valid_span(note.get("start_index"), note.get("end_index"), len(text))
)
for note in citations:
url = note["url"]
if x_posts_only and not _is_x_post(url):
continue
source: dict[str, Any] = {"url": url}
title = note.get("title")
# xAI numbers its citations ("1", "2"); a number is not a title.
if isinstance(title, str) and title.strip() and not title.strip().isdigit():
source["title"] = title.strip()
start, end = note.get("start_index"), note.get("end_index")
if _valid_span(start, end, len(text)):
snippet = excerpt(text, start, end, url, spans)
if snippet:
source["snippet"] = snippet
sources.append(source)
return sources
def _valid_span(start: Any, end: Any, length: int) -> bool:
return (
isinstance(start, int) and isinstance(end, int)
and not isinstance(start, bool) and not isinstance(end, bool)
and 0 <= start < end <= length
)
def _is_x_post(url: str) -> bool:
match = re.match(r"https?://([^/]+)/", url)
return match is not None and match.group(1).lower() in _X_POST_HOSTS
def _merge_sources(*groups: list[dict[str, Any]]) -> list[dict[str, Any]]:
merged: dict[str, dict[str, Any]] = {}
for group in groups:
for source in group:
known = merged.setdefault(source["url"], {"url": source["url"]})
for key, value in source.items():
known.setdefault(key, value)
return list(merged.values())
_SENTENCE_END = re.compile(r"[.!?。!?](?=\s|$)")
_LIST_MARKER = re.compile(r"^\s*(?:[-*•]|\d+[.)])\s*")
def excerpt(text: str, start: int, end: int, url: str, spans: list[tuple[int, int, str]]) -> str | None:
"""The answer text a citation span belongs to, without citation markers (``vibey-hosted-tools.md`` §12 item 24).
``spans`` are the text's citation spans, in text order.
The executor asks for one list item per result, each ending in its
citation, so a span on a line that cites only its own URL takes that whole
line. On a line that cites several sources, it takes its sentence: the one
it sits in, or the one it follows (``It rose 5%. ([site](url))``). Every
citation span, a leading list marker and bold markers are removed.
"""
line_start = text.rfind("\n", 0, start) + 1
line_end = text.find("\n", end)
line_end = len(text) if line_end == -1 else line_end
on_line = [span for span in spans if span[0] >= line_start and span[1] <= line_end]
if all(span[2] == url for span in on_line):
region_start, region_end = line_start, line_end
else:
region_start, region_end = _sentence(text, start, end, line_start, line_end)
pieces, cursor = [], region_start
for span_start, span_end, _url in spans:
if span_end <= region_start or span_start >= region_end:
continue
pieces.append(text[cursor:max(cursor, span_start)])
cursor = max(cursor, span_end)
if cursor < region_end:
pieces.append(text[cursor:region_end])
snippet = " ".join(_LIST_MARKER.sub("", "".join(pieces), count=1).replace("**", "").split())
snippet = re.sub(r"\s+([.,;:!?])", r"\1", snippet)
if len(snippet) > _SNIPPET_CHARS:
snippet = snippet[: _SNIPPET_CHARS - 1].rstrip() + "…"
return snippet or None
def _sentence(text: str, start: int, end: int, line_start: int, line_end: int) -> tuple[int, int]:
"""The sentence of a line a citation span belongs to: the one it sits in, or the one it follows."""
before = text[line_start:start].rstrip()
trailing = bool(before) and not _LIST_MARKER.fullmatch(before) and before[-1] in ".!?。!?"
anchor = line_start + len(before) - 1 if trailing else start
sentence_start = line_start
for match in _SENTENCE_END.finditer(text, line_start, anchor):
sentence_start = match.end()
if trailing:
return sentence_start, line_start + len(before)
found = _SENTENCE_END.search(text, end, line_end)
return sentence_start, found.end() if found is not None else line_end
def anthropic_result(body: bytes | bytearray, say: Say) -> ExecutorResult:
"""The canonical record of one buffered Anthropic web search executor call; parse it off the loop."""
try:
message = json.loads(body)
except (ValueError, RecursionError):
return ExecutorResult(failed_record(failure(say, "modelHub.hostedTools.unreadable")))
return replace(_anthropic_record(message, say), usage=_usage_section(message))
def _anthropic_record(message: Any, say: Say) -> ExecutorResult:
content = message.get("content") if isinstance(message, dict) else None
blocks = [block for block in content if isinstance(block, dict)] if isinstance(content, list) else []
if not any(block.get("type") == "server_tool_use" and block.get("name") == "web_search" for block in blocks):
return ExecutorResult(failed_record(failure(say, "modelHub.hostedTools.didNotRun", tool="web_search")))
results: list[dict[str, Any]] = []
errors: list[str] = []
for block in blocks:
if block.get("type") != "web_search_tool_result":
continue
found = block.get("content")
if isinstance(found, dict):
errors.append(str(found.get("error_code") or "unknown"))
continue
if not isinstance(found, list):
# Only a list, possibly empty, is a result; anything else is not an answer.
return ExecutorResult(failed_record(failure(say, "modelHub.hostedTools.unreadable")))
for result in found:
if isinstance(result, dict) and isinstance(result.get("url"), str) and result["url"]:
source = {"url": result["url"]}
for key in ("title", "page_age"):
if isinstance(result.get(key), str) and result[key]:
source[key] = result[key]
results.append(source)
cited = [
{"url": citation["url"], "snippet": " ".join(citation["cited_text"].split())}
for block in blocks
if block.get("type") == "text"
for citation in (block.get("citations") if isinstance(block.get("citations"), list) else ())
if isinstance(citation, dict)
and isinstance(citation.get("url"), str)
and citation["url"]
and isinstance(citation.get("cited_text"), str)
and citation["cited_text"].strip()
][:_MAX_CITATIONS]
# Results keep the provider's order; a cited result gains the text it was cited for.
sources = _merge_sources(results, cited)
if errors:
# Any search the provider marked failed fails the call, as on Responses;
# the results that did arrive stay as partial sources.
failed = failure(say, "modelHub.hostedTools.callFailed", tool="web_search", provider_says=", ".join(errors))
return ExecutorResult(failed_record(failed, sources))
# Success is an allow-list here too: an early stop is incomplete, anything else unknown fails.
stop = _text_field(message, "stop_reason")
if stop in {"end_turn", "stop_sequence"}:
uses = [
block.get("id") for block in blocks
if block.get("type") == "server_tool_use" and block.get("name") == "web_search"
]
answered = [block.get("tool_use_id") for block in blocks if block.get("type") == "web_search_tool_result"]
if not all(isinstance(ident, str) and ident for ident in (*uses, *answered)) or not set(uses) <= set(answered):
# A finished response must carry every search's result block, even an empty one.
return ExecutorResult(failed_record(failure(say, "modelHub.hostedTools.unreadable"), sources))
return ExecutorResult({"status": "completed", "sources": sources})
ended = failure(say, "modelHub.hostedTools.responseEnded", status=str(stop or "unknown"))
return ExecutorResult(failed_record(ended, sources, status="incomplete" if stop in {"max_tokens", "pause_turn"} else "failed"))
def google_result(body: bytes | bytearray, say: Say) -> ExecutorResult:
"""The canonical record of one buffered Gemini Google Search executor call; parse it off the loop."""
try:
response = json.loads(body)
except (ValueError, RecursionError):
return ExecutorResult(failed_record(failure(say, "modelHub.hostedTools.unreadable")))
return _google_record(response if isinstance(response, dict) else {}, say)
def _google_record(response: Mapping[str, Any], say: Say) -> ExecutorResult:
"""Gemini answers in one response: its text, and the search's queries, sources and supports in its
``groundingMetadata``. Sources keep Google's order, each once; a supported one gains its line of the answer."""
candidates = response.get("candidates")
candidate = candidates[0] if isinstance(candidates, list) and candidates and isinstance(candidates[0], dict) else {}
grounding = candidate.get("groundingMetadata")
grounding = grounding if isinstance(grounding, dict) else {}
queries = grounding.get("webSearchQueries")
if not any(isinstance(query, str) and query.strip() for query in (queries if isinstance(queries, list) else ())):
feedback = response.get("promptFeedback")
blocked = feedback.get("blockReason") if isinstance(feedback, dict) else None
if isinstance(blocked, str) and blocked:
return ExecutorResult(failed_record(failure(say, "modelHub.hostedTools.responseEnded", status=blocked)))
return ExecutorResult(failed_record(failure(say, "modelHub.hostedTools.didNotRun", tool="web_search")))
content = candidate.get("content")
parts = content.get("parts") if isinstance(content, dict) else None
text = "".join(
part["text"] for part in (parts if isinstance(parts, list) else ())
if isinstance(part, dict) and isinstance(part.get("text"), str) and part.get("thought") is not True
)
chunks = grounding.get("groundingChunks")
chunks = chunks if isinstance(chunks, list) else []
sources: list[dict[str, Any]] = []
by_chunk: dict[int, dict[str, Any]] = {}
for index, chunk in enumerate(chunks):
web = chunk.get("web") if isinstance(chunk, dict) else None
url = _text_field(web, "uri") if isinstance(web, dict) else None
if not url:
continue
known = next((source for source in sources if source["url"] == url), None)
if known is None:
known = {"url": url}
title = _text_field(web, "title")
if title and title.strip():
known["title"] = title.strip()
sources.append(known)
by_chunk[index] = known
cursor = 0
supports = grounding.get("groundingSupports")
for support in (supports if isinstance(supports, list) else ())[:_MAX_CITATIONS]:
segment = support.get("segment") if isinstance(support, dict) else None
cited = _text_field(segment, "text") if isinstance(segment, dict) else None
indices = support.get("groundingChunkIndices") if isinstance(support, dict) else None
if not cited or not isinstance(indices, list):
continue
# Located in the text, in order: Google's offsets count bytes, and a sentence may recur.
start = text.find(cited, cursor)
start = text.find(cited) if start < 0 else start
if start < 0:
continue
cursor = start + len(cited)
for number in indices:
source = by_chunk.get(number) if isinstance(number, int) and not isinstance(number, bool) else None
if source is not None and "snippet" not in source:
snippet = excerpt(text, start, start + len(cited), source["url"], [])
if snippet:
source["snippet"] = snippet
# Success is an allow-list here too: an early stop is incomplete, anything else fails.
finish = _text_field(candidate, "finishReason")
if finish == "STOP":
return ExecutorResult({"status": "completed", "sources": sources}, usage=grounding)
ended = failure(say, "modelHub.hostedTools.responseEnded", status=str(finish or "unknown"))
record = failed_record(ended, sources, status="incomplete" if finish == "MAX_TOKENS" else "failed")
return ExecutorResult(record, usage=grounding)