cuery.search
============

.. py:module:: cuery.search

.. autoapi-nested-parse::

   Async helpers for grounded / live web search via OpenAI, Google Gemini and xAI Grok.

   Provides a convenience ``search`` function that executes multiple web searches
   concurrently (rate limited via a semaphore) and preserves input order. Logic
   mirrors :func:`cuery.call.gather_calls` but is simplified for plain string prompts.

   Currently supported providers (``client`` argument):

   * ``"openai"`` – Uses the OpenAI Responses API with the ``web_search_preview`` tool.
   * ``"gemini"`` – Uses the Google Gemini (google-genai) API with Google Search grounding
       (``google_search`` for Gemini 2.x, ``google_search_retrieval`` for 1.5 models).

   Both return a :class:`SearchResult` with extracted plain text plus a list of
   ``Reference`` objects (title + URL) when available. If parsing fails a ``ValueError``
   is raised (no silent fallbacks here – upstream caller can decide how to handle).



Attributes
----------

.. autoapisummary::

   cuery.search.OAIResponse
   cuery.search.VALID_MODELS
   cuery.search.__md
   cuery.search.LLMS
   cuery.search.FORMATTED_SEARCH_PROMPT
   cuery.search.SUPPORT_COUNTRY


Classes
-------

.. autoapisummary::

   cuery.search.Source
   cuery.search.SearchResult


Functions
---------

.. autoapisummary::

   cuery.search.unmark_element
   cuery.search.unmark
   cuery.search.resolve_redirect
   cuery.search.validate_openai
   cuery.search.validate_gemini
   cuery.search.validate_xai
   cuery.search.query_openai
   cuery.search.coords
   cuery.search.query_gemini
   cuery.search.query_xai
   cuery.search.query_deepseek
   cuery.search.validate_model
   cuery.search.search_with_format
   cuery.search.gather


Module Contents
---------------

.. py:data:: OAIResponse

.. py:data:: VALID_MODELS

.. py:function:: unmark_element(element, stream=None)

.. py:data:: __md

.. py:function:: unmark(text)

   Convert Markdown text to plain text, stripping all formatting.


.. py:class:: Source(/, **data)

   Bases: :py:obj:`cuery.response.Response`


   Single search reference with title and URL.


   .. py:attribute:: title
      :type:  str


   .. py:attribute:: url
      :type:  str


   .. py:property:: domain
      :type: str | None


      Extract domain from URL.


.. py:class:: SearchResult(/, **data)

   Bases: :py:obj:`cuery.response.Response`


   Search result with extracted text and references.


   .. py:attribute:: answer
      :type:  str


   .. py:attribute:: sources
      :type:  list[Source]


.. py:function:: resolve_redirect(redirect_url, timeout = 2)

   Resolve a URL redirect to its final destination URL.

   Gemini grounding chunk URIs are things like:
   https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQFXCboQq0LRg6hUOP...


.. py:function:: validate_openai(response, plain = False)

   Convert a raw web search response into a ``SearchResult`` instance.


.. py:function:: validate_gemini(response, plain = False)

   Convert a Gemini grounded search raw response into ``SearchResult``.


.. py:function:: validate_xai(response, plain = False)

   Convert an xAI Grok Live Search chat completion into ``SearchResult``.

   Citations (if ``return_citations`` enabled – default true) are exposed as a
   list of URL strings on ``response.citations``. We map each into a ``Reference``
   using the URL as both title and URL (title data not currently provided).


.. py:function:: query_openai(prompt, country = None, city = None, context_size = 'medium', reasoning_effort = 'low', model = 'gpt-4.1-mini', use_search = True, validate = True, response_format = None)
   :async:


   Call OpenAI Responses API with Web Search enabled (async).

   API Docs:
   - https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses


.. py:function:: coords(country)

.. py:function:: query_gemini(prompt, model = 'gemini-2.0-flash', country = None, language = None, thinking_budget = -1, use_search = True, validate = True)
   :async:


   Call Gemini with Google Search grounding (supports Gemini > 2.0 only).

   API Docs:
   - https://ai.google.dev/gemini-api/docs/google-search
   - https://ai.google.dev/gemini-api/docs/thinking


.. py:function:: query_xai(prompt, model = 'grok-4', timeout = None, mode = 'on', max_search_results = 15, sources = None, country = None, use_search = True, validate = True)
   :async:


   Call xAI Grok with Live Search (async).

   API Docs:
   - https://docs.x.ai/docs/guides/live-search


.. py:function:: query_deepseek(prompt, model = 'deepseek-chat', validate = True, use_search = True, **kwds)
   :async:


   DeepSeek doesn't support search yet, so we simply execute the prompt as-is.


.. py:data:: LLMS

.. py:function:: validate_model(client, model)

   Validate if the given client and model are supported.


.. py:data:: FORMATTED_SEARCH_PROMPT
   :value: ''


.. py:function:: search_with_format(prompt, model, response_format, **kwds)
   :async:


   Perform a web search using the specified model and return structured response.


.. py:data:: SUPPORT_COUNTRY
   :value: ['openai', 'xai', 'google']


.. py:function:: gather(prompts, model = 'openai/gpt-4.1-mini', use_search = True, country = None, validate = True, policies = None, execute = True, **kwds)
   :async:


   Simplified gather mirroring ``hasdata.gather`` using ``all_with_policies``.

   Creates one coroutine per prompt for the selected model/provider with optional
   policies (timeout, retries, semaphore, fallback, progress). When ``execute`` is
   False the wrapped coroutine objects are returned for the caller to schedule.