From 8e2770c036c106fefa28e07f21129241c02c932a Mon Sep 17 00:00:00 2001 From: Ricardo Batista <138892976+rbatista191@users.noreply.github.com> Date: Fri, 6 Nov 2026 06:05:39 +0100 Subject: [PATCH 1/3] feat(search): add cloro as a /v1/search provider --- .github/workflows/test-unit.yml | 1 + litellm/llms/cloro/search/__init__.py | 7 + litellm/llms/cloro/search/transformation.py | 166 ++++++++++++++++++ ...odel_prices_and_context_window_backup.json | 8 + .../provider_endpoints_support_backup.json | 26 +++ litellm/types/utils.py | 1 + litellm/utils.py | 2 + model_prices_and_context_window.json | 8 + provider_endpoints_support.json | 26 +++ .../enforce_llms_folder_style.py | 1 + .../search/test_base_search_transformation.py | 3 + tests/unit/llms/cloro/__init__.py | 0 tests/unit/llms/cloro/search/__init__.py | 0 .../test_cloro_search_transformation.py | 162 +++++++++++++++++ 14 files changed, 411 insertions(+) create mode 100644 litellm/llms/cloro/search/__init__.py create mode 100644 litellm/llms/cloro/search/transformation.py create mode 100644 tests/unit/llms/cloro/__init__.py create mode 100644 tests/unit/llms/cloro/search/__init__.py create mode 100644 tests/unit/llms/cloro/search/test_cloro_search_transformation.py diff --git a/.github/workflows/test-unit.yml b/.github/workflows/test-unit.yml index 41198887cab..4b2eefcc7bf 100644 --- a/.github/workflows/test-unit.yml +++ b/.github/workflows/test-unit.yml @@ -275,6 +275,7 @@ jobs: tests/unit/llms/clarifai tests/unit/llms/claude_code tests/unit/llms/clf_ai_gateway + tests/unit/llms/cloro tests/unit/llms/cloudflare tests/unit/llms/codestral tests/unit/llms/codex diff --git a/litellm/llms/cloro/search/__init__.py b/litellm/llms/cloro/search/__init__.py new file mode 100644 index 00000000000..6bd5ba0b480 --- /dev/null +++ b/litellm/llms/cloro/search/__init__.py @@ -0,0 +1,7 @@ +""" +cloro Search API module. +""" + +from litellm.llms.cloro.search.transformation import CloroSearchConfig + +__all__ = ["CloroSearchConfig"] diff --git a/litellm/llms/cloro/search/transformation.py b/litellm/llms/cloro/search/transformation.py new file mode 100644 index 00000000000..ccf6089d1fc --- /dev/null +++ b/litellm/llms/cloro/search/transformation.py @@ -0,0 +1,166 @@ +""" +cloro Google Search API. +Endpoint: POST https://api.cloro.dev/v1/monitor/google +Docs: https://cloro.dev/docs/api-reference/endpoint/monitor-google?utm_source=litellm&utm_medium=byok +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from typing import Final +from urllib.parse import urlsplit + +import httpx +from pydantic import ConfigDict, TypeAdapter, ValidationError + +from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj +from litellm.litellm_core_utils.url_utils import ensure_api_route +from litellm.llms.base_llm.search.transformation import ( + BaseSearchConfig, + SearchResponse, + SearchResult, +) +from litellm.secret_managers.main import get_secret_str + +_JSON_OBJECT: Final = TypeAdapter(Mapping[str, object], config=ConfigDict(hide_input_in_errors=True)) +_JSON_OBJECTS: Final = TypeAdapter(Sequence[Mapping[str, object]], config=ConfigDict(hide_input_in_errors=True)) +_STR_LIST: Final = TypeAdapter(list[str]) + +CLORO_DEFAULT_COUNTRY: Final = "US" +_CLORO_GOOGLE_ROUTE: Final = "v1/monitor/google" + + +class CloroSearchConfig(BaseSearchConfig): + CLORO_API_BASE = "https://api.cloro.dev" + + @staticmethod + def ui_friendly_name() -> str: + return "cloro (Google Search)" + + def validate_environment( + self, + headers: dict[str, str], # mutable-ok: BaseSearchConfig.validate_environment signature + api_key: str | None = None, + api_base: str | None = None, + **kwargs: object, # kwargs-ok: BaseSearchConfig.validate_environment signature + ) -> dict[str, str]: # mutable-ok: the http handler passes this straight to httpx as headers + resolved_key: Final = self.resolve_server_api_key( + caller_api_key=api_key, + caller_api_base=api_base, + key_env_vars=("CLORO_API_KEY",), + base_env_var="CLORO_API_BASE", + default_api_base=self.CLORO_API_BASE, + ) + if not resolved_key: + raise ValueError("CLORO_API_KEY is not set. Set `CLORO_API_KEY` environment variable.") + return {**headers, "Authorization": f"Bearer {resolved_key}", "Content-Type": "application/json"} + + def get_complete_url( + self, + api_base: str | None, + optional_params: dict[str, object], # mutable-ok: BaseSearchConfig.get_complete_url signature + data: dict[str, object] | list[dict[str, object]] | None = None, # mutable-ok: base signature + **kwargs: object, # kwargs-ok: BaseSearchConfig.get_complete_url signature + ) -> str: + resolved_base: Final = api_base or get_secret_str("CLORO_API_BASE") or self.CLORO_API_BASE + return ensure_api_route(resolved_base, _CLORO_GOOGLE_ROUTE) + + def transform_search_request( + self, + query: str | list[str], # mutable-ok: BaseSearchConfig.transform_search_request signature + optional_params: dict[str, object], # mutable-ok: base signature + **kwargs: object, # kwargs-ok: BaseSearchConfig.transform_search_request signature + ) -> dict[str, object]: # mutable-ok: the http handler sends this as the JSON body + """ + Unified params -> cloro body: ``query`` (list joined with spaces, ``search_domain_filter`` + folded in as ``site:`` operators), ``country`` upper-cased and sent as ``US`` when absent, + because cloro requires it. ``max_results`` has no cloro equivalent: one call returns one + Google results page, and the response is cut to ``max_results``. ``max_tokens_per_page`` is + dropped. Everything outside the unified spec (``include``, ``device``, ``location``, + ``pages``, ``hl``) is forwarded as-is. + """ + joined_query: Final = " ".join(query) if isinstance(query, list) else query + domains: Final = _domain_filter(optional_params.get("search_domain_filter")) + country: Final = optional_params.get("country") + unified: Final = self.get_supported_perplexity_optional_params() + passthrough: Final = {k: v for k, v in optional_params.items() if k not in unified} + return { + **passthrough, + "query": _with_site_filters(joined_query, domains), + "country": country.upper() if isinstance(country, str) and country else CLORO_DEFAULT_COUNTRY, + } + + def transform_search_response( + self, + raw_response: httpx.Response, + logging_obj: LiteLLMLoggingObj, + **kwargs: object, # kwargs-ok: BaseSearchConfig.transform_search_response signature + ) -> SearchResponse: + """ + ``result.organicResults[]`` -> results, without rows whose ``link`` is empty or a Google + ``/goto`` redirect, cut to ``max_results``. Every other key of ``result`` + (``peopleAlsoAsk``, ``relatedSearches``, ``ads``, and ``aioverview`` when + ``include={"aioverview": True}`` was sent) -> ``SearchResponse.provider_metadata``. + """ + response_json: Final = _JSON_OBJECT.validate_python(raw_response.json()) + result: Final = _JSON_OBJECT.validate_python(response_json.get("result", {})) + rows: Final = _JSON_OBJECTS.validate_python(result.get("organicResults", ())) + results: Final = [_to_search_result(row) for row in rows if _is_direct_link(row.get("link"))] + limit: Final = _max_results(kwargs.get("optional_params")) + return SearchResponse.model_validate( + { + "results": results[:limit] if limit is not None else results, + "object": "search", + "provider_metadata": {key: value for key, value in result.items() if key != "organicResults"}, + } + ) + + +def _domain_filter(raw: object) -> tuple[str, ...]: + try: + return tuple(_STR_LIST.validate_python(raw)) + except ValidationError: + return () + + +def _with_site_filters(query: str, domains: tuple[str, ...]) -> str: + if not domains: + return query + site_clause: Final = " OR ".join(f"site:{domain}" for domain in domains) + return f"({query}) ({site_clause})" + + +def _max_results(optional_params: object) -> int | None: + try: + params: Final = _JSON_OBJECT.validate_python(optional_params) + except ValidationError: + return None + raw: Final = params.get("max_results") + if isinstance(raw, bool) or not isinstance(raw, int): + return None + return max(1, raw) + + +def _is_direct_link(link: object) -> bool: + if not isinstance(link, str) or not link: + return False + parts: Final = urlsplit(link) + host: Final = (parts.hostname or "").lower() + is_google_host: Final = host == "google.com" or host.endswith(".google.com") + return not (is_google_host and parts.path.startswith("/goto")) + + +def _to_search_result(row: Mapping[str, object]) -> SearchResult: + return SearchResult.model_validate( + { + "title": _as_str(row.get("title")), + "url": _as_str(row.get("link")), + "snippet": _as_str(row.get("snippet")), + "date": None, + "last_updated": None, + } + ) + + +def _as_str(value: object) -> str: + return value if isinstance(value, str) else "" diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json index ad57685da04..25198b5144d 100644 --- a/litellm/model_prices_and_context_window_backup.json +++ b/litellm/model_prices_and_context_window_backup.json @@ -25407,6 +25407,14 @@ "notes": "SearXNG is an open-source metasearch engine. Free to use when self-hosted or using public instances." } }, + "cloro/search": { + "input_cost_per_query": 0.004, + "litellm_provider": "cloro", + "mode": "search", + "metadata": { + "notes": "cloro Google Search, sync, one results page: 5 credits a query. Lite plan list price: $30 for 37,500 credits ($0.80 per 1,000 credits), so $0.004 a query. include.aioverview adds 2 credits a query and each extra page adds 2 credits. Larger plans price a credit lower." + } + }, "serper/search": { "input_cost_per_query": 0.001, "litellm_provider": "serper", diff --git a/litellm/provider_endpoints_support_backup.json b/litellm/provider_endpoints_support_backup.json index 00fee0a0d5a..6864ae5ede8 100644 --- a/litellm/provider_endpoints_support_backup.json +++ b/litellm/provider_endpoints_support_backup.json @@ -4124,6 +4124,32 @@ "generateContent": false } }, + "cloro": { + "display_name": "cloro (`cloro`)", + "url": "https://docs.litellm.ai/docs/search/cloro", + "endpoints": { + "chat_completions": false, + "responses": false, + "text_completion": false, + "embeddings": false, + "image_generations": false, + "image_edits": false, + "audio_transcriptions": false, + "audio_speech": false, + "rerank": false, + "ocr": false, + "search": true, + "moderations": false, + "realtime": false, + "video_generations": false, + "batches": false, + "messages": false, + "interactions": false, + "systemone": false, + "a2a": false, + "generateContent": false + } + }, "serper": { "display_name": "Serper (`serper`)", "url": "https://docs.litellm.ai/docs/search/serper", diff --git a/litellm/types/utils.py b/litellm/types/utils.py index 7c137b72c3e..8ce2cda830e 100644 --- a/litellm/types/utils.py +++ b/litellm/types/utils.py @@ -4843,6 +4843,7 @@ class SearchProviders(str, Enum): BING_GROUNDING = "bing_grounding" DEEPSEEK = "deepseek" XAI = "xai" + CLORO = "cloro" # Create a set of all search provider values for quick lookup diff --git a/litellm/utils.py b/litellm/utils.py index 53b02ebddac..ce31a2526a3 100644 --- a/litellm/utils.py +++ b/litellm/utils.py @@ -11433,6 +11433,7 @@ class ProviderConfigManager: from litellm.llms.azure.search.transformation import BingGroundingSearchConfig from litellm.llms.bedrock.search.transformation import AgentCoreSearchConfig from litellm.llms.brave.search.transformation import BraveSearchConfig + from litellm.llms.cloro.search.transformation import CloroSearchConfig from litellm.llms.dataforseo.search.transformation import DataForSEOSearchConfig from litellm.llms.deepseek.search.transformation import DeepSeekSearchConfig from litellm.llms.duckduckgo.search.transformation import DuckDuckGoSearchConfig @@ -11477,6 +11478,7 @@ class ProviderConfigManager: SearchProviders.BING_GROUNDING: BingGroundingSearchConfig, SearchProviders.DEEPSEEK: DeepSeekSearchConfig, SearchProviders.XAI: XAISearchConfig, + SearchProviders.CLORO: CloroSearchConfig, } config_class: Final = PROVIDER_TO_CONFIG_MAP.get(provider, None) if config_class is None: diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json index ad57685da04..25198b5144d 100644 --- a/model_prices_and_context_window.json +++ b/model_prices_and_context_window.json @@ -25407,6 +25407,14 @@ "notes": "SearXNG is an open-source metasearch engine. Free to use when self-hosted or using public instances." } }, + "cloro/search": { + "input_cost_per_query": 0.004, + "litellm_provider": "cloro", + "mode": "search", + "metadata": { + "notes": "cloro Google Search, sync, one results page: 5 credits a query. Lite plan list price: $30 for 37,500 credits ($0.80 per 1,000 credits), so $0.004 a query. include.aioverview adds 2 credits a query and each extra page adds 2 credits. Larger plans price a credit lower." + } + }, "serper/search": { "input_cost_per_query": 0.001, "litellm_provider": "serper", diff --git a/provider_endpoints_support.json b/provider_endpoints_support.json index 00fee0a0d5a..6864ae5ede8 100644 --- a/provider_endpoints_support.json +++ b/provider_endpoints_support.json @@ -4124,6 +4124,32 @@ "generateContent": false } }, + "cloro": { + "display_name": "cloro (`cloro`)", + "url": "https://docs.litellm.ai/docs/search/cloro", + "endpoints": { + "chat_completions": false, + "responses": false, + "text_completion": false, + "embeddings": false, + "image_generations": false, + "image_edits": false, + "audio_transcriptions": false, + "audio_speech": false, + "rerank": false, + "ocr": false, + "search": true, + "moderations": false, + "realtime": false, + "video_generations": false, + "batches": false, + "messages": false, + "interactions": false, + "systemone": false, + "a2a": false, + "generateContent": false + } + }, "serper": { "display_name": "Serper (`serper`)", "url": "https://docs.litellm.ai/docs/search/serper", diff --git a/tests/code_coverage_tests/enforce_llms_folder_style.py b/tests/code_coverage_tests/enforce_llms_folder_style.py index a284cf9e1a9..84763185516 100644 --- a/tests/code_coverage_tests/enforce_llms_folder_style.py +++ b/tests/code_coverage_tests/enforce_llms_folder_style.py @@ -21,6 +21,7 @@ SEARCH_PROVIDERS = [ "apiserpent", "tinyfish", "nimble", + "cloro", ] ALLOWED_FILES_IN_LLMS_FOLDER = [ diff --git a/tests/unit/llms/base_llm/search/test_base_search_transformation.py b/tests/unit/llms/base_llm/search/test_base_search_transformation.py index e6aad7688d1..f30007c86d4 100644 --- a/tests/unit/llms/base_llm/search/test_base_search_transformation.py +++ b/tests/unit/llms/base_llm/search/test_base_search_transformation.py @@ -22,6 +22,7 @@ from litellm.llms.base_llm.search.transformation import ( _is_trusted_search_api_base, ) from litellm.llms.brave.search.transformation import BraveSearchConfig +from litellm.llms.cloro.search.transformation import CloroSearchConfig from litellm.llms.dataforseo.search.transformation import DataForSEOSearchConfig from litellm.llms.exa_ai.search.transformation import ExaAISearchConfig from litellm.llms.fastcrw.search.transformation import FastCRWSearchConfig @@ -61,6 +62,7 @@ _BASE_ENV_VARS = ( "CRW_API_BASE", "NIMBLE_API_BASE", "BING_GROUNDING_PROJECT_ENDPOINT", + "CLORO_API_BASE", ) @@ -102,6 +104,7 @@ PROVIDERS: Tuple[ProviderSpec, ...] = ( (FastCRWSearchConfig, {"CRW_API_KEY": "srv"}, "caller-key", {}), (NimbleSearchConfig, {"NIMBLE_API_KEY": "srv"}, "caller-key", {}), (BingGroundingSearchConfig, {"BING_GROUNDING_TOKEN": "srv"}, "caller-key", {}), + (CloroSearchConfig, {"CLORO_API_KEY": "srv"}, "caller-key", {}), ) _IDS = tuple(spec[0].__name__ for spec in PROVIDERS) diff --git a/tests/unit/llms/cloro/__init__.py b/tests/unit/llms/cloro/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/unit/llms/cloro/search/__init__.py b/tests/unit/llms/cloro/search/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/unit/llms/cloro/search/test_cloro_search_transformation.py b/tests/unit/llms/cloro/search/test_cloro_search_transformation.py new file mode 100644 index 00000000000..7dcb9a9d315 --- /dev/null +++ b/tests/unit/llms/cloro/search/test_cloro_search_transformation.py @@ -0,0 +1,162 @@ +""" +Tests for the cloro Search provider (POST https://api.cloro.dev/v1/monitor/google). +""" + +from typing import Final +from unittest.mock import AsyncMock, MagicMock, patch + +import httpx +import pytest + +import litellm +from litellm.llms.cloro.search.transformation import CloroSearchConfig + +AI_OVERVIEW: Final = { + "text": "Rank trackers report where a page ranks for a keyword.", + "sources": [{"label": "Rank tracker guide", "url": "https://example.com/guide", "position": 1}], + "citationPills": [], +} + +PEOPLE_ALSO_ASK: Final = [{"question": "What is the best rank tracker tool?", "type": "AIOVERVIEW"}] + + +def _organic_row(position: int, link: str) -> dict[str, object]: + return { + "position": position, + "title": f"Result {position}", + "link": link, + "displayedLink": "https://example.com > results", + "snippet": f"Snippet {position}", + "page": 1, + "redirectLink": f"https://www.google.com/goto?url=CAES{position}", + } + + +def _cloro_response(rows: list[dict[str, object]], **extra: object) -> httpx.Response: + return httpx.Response( + 200, + json={"success": True, "result": {"organicResults": rows, "peopleAlsoAsk": PEOPLE_ALSO_ASK, **extra}}, + ) + + +@pytest.mark.asyncio +async def test_asearch_sends_cloro_body_and_maps_results(monkeypatch): + monkeypatch.setenv("CLORO_API_KEY", "test-cloro-key") + monkeypatch.delenv("CLORO_API_BASE", raising=False) + mock_response: Final = MagicMock() + mock_response.status_code = 200 + mock_response.json.return_value = { + "success": True, + "result": { + "organicResults": [_organic_row(1, "https://example.com/1"), _organic_row(2, "https://example.com/2")], + "peopleAlsoAsk": PEOPLE_ALSO_ASK, + "aioverview": AI_OVERVIEW, + }, + } + + with patch( + "litellm.llms.custom_httpx.http_handler.AsyncHTTPHandler.post", + new_callable=AsyncMock, + return_value=mock_response, + ) as mock_post: + response: Final = await litellm.asearch( + query="best rank tracker", + search_provider="cloro", + country="de", + search_domain_filter=["example.com"], + include={"aioverview": True}, + ) + + call: Final = mock_post.call_args + assert call.kwargs["url"] == "https://api.cloro.dev/v1/monitor/google" + assert call.kwargs["headers"]["Authorization"] == "Bearer test-cloro-key" + assert call.kwargs["json"] == { + "query": "(best rank tracker) (site:example.com)", + "country": "DE", + "include": {"aioverview": True}, + } + assert [(r.title, r.url, r.snippet) for r in response.results] == [ + ("Result 1", "https://example.com/1", "Snippet 1"), + ("Result 2", "https://example.com/2", "Snippet 2"), + ] + assert response.provider_metadata == {"peopleAlsoAsk": PEOPLE_ALSO_ASK, "aioverview": AI_OVERVIEW} + + +def test_country_defaults_to_us_because_cloro_requires_it(): + body: Final = CloroSearchConfig().transform_search_request(query=["rank", "tracker"], optional_params={}) + assert body == {"query": "rank tracker", "country": "US"} + + +def test_unified_params_without_cloro_equivalent_are_not_sent(): + body: Final = CloroSearchConfig().transform_search_request( + query="litellm", + optional_params={"max_results": 3, "max_tokens_per_page": 1024, "device": "mobile", "pages": 2}, + ) + assert body == {"query": "litellm", "country": "US", "device": "mobile", "pages": 2} + + +def test_rows_without_a_direct_link_are_dropped(): + rows: Final = [ + _organic_row(1, ""), + _organic_row(2, "https://www.google.com/goto?url=CAES2"), + {"title": "No link at all"}, + _organic_row(4, "https://example.com/4"), + ] + response: Final = CloroSearchConfig().transform_search_response( + raw_response=_cloro_response(rows), logging_obj=MagicMock() + ) + assert [r.url for r in response.results] == ["https://example.com/4"] + + +@pytest.mark.parametrize(("max_results", "expected_count"), [(1, 1), (2, 2), (50, 3), (0, 1)]) +def test_results_are_cut_to_max_results(max_results, expected_count): + rows: Final = [_organic_row(i, f"https://example.com/{i}") for i in range(1, 4)] + response: Final = CloroSearchConfig().transform_search_response( + raw_response=_cloro_response(rows), + logging_obj=MagicMock(), + optional_params={"max_results": max_results}, + ) + assert len(response.results) == expected_count + + +def test_missing_organic_results_is_an_empty_search(): + response: Final = CloroSearchConfig().transform_search_response( + raw_response=httpx.Response(200, json={"success": True, "result": {"relatedSearches": []}}), + logging_obj=MagicMock(), + ) + assert response.results == [] + assert response.provider_metadata == {"relatedSearches": []} + + +@pytest.mark.parametrize( + "api_base", + [None, "https://api.cloro.dev", "https://api.cloro.dev/", "https://api.cloro.dev/v1/monitor/google"], +) +def test_complete_url_resolves_google_route(api_base, monkeypatch): + monkeypatch.delenv("CLORO_API_BASE", raising=False) + url: Final = CloroSearchConfig().get_complete_url(api_base=api_base, optional_params={}) + assert url == "https://api.cloro.dev/v1/monitor/google" + + +def test_missing_api_key_raises(monkeypatch): + monkeypatch.delenv("CLORO_API_KEY", raising=False) + with pytest.raises(ValueError, match="CLORO_API_KEY"): + CloroSearchConfig().validate_environment(headers={}) + + +def test_search_cost_comes_from_cost_map(monkeypatch): + monkeypatch.setenv("CLORO_API_KEY", "test-cloro-key") + priced: Final[float] = litellm.model_cost["cloro/search"]["input_cost_per_query"] + assert priced > 0 + mock_response: Final = MagicMock() + mock_response.status_code = 200 + mock_response.json.return_value = { + "success": True, + "result": {"organicResults": [_organic_row(1, "https://example.com/1")]}, + } + with patch( + "litellm.llms.custom_httpx.http_handler.HTTPHandler.post", + return_value=mock_response, + ): + response: Final = litellm.search(query="litellm", search_provider="cloro") + assert response._hidden_params["response_cost"] == pytest.approx(priced) From 01b0a684e59ebabec776783f6fff9c82a3ff1767 Mon Sep 17 00:00:00 2001 From: Ricardo Batista <138892976+rbatista191@users.noreply.github.com> Date: Fri, 6 Nov 2026 07:40:01 +0100 Subject: [PATCH 2/3] fix(search): bill cloro searches by the credits cloro reports --- litellm/llms/cloro/search/transformation.py | 33 ++++++++- ...odel_prices_and_context_window_backup.json | 2 +- litellm/search/cost_calculator.py | 11 +++ model_prices_and_context_window.json | 2 +- .../test_cloro_search_transformation.py | 72 ++++++++++++------- 5 files changed, 93 insertions(+), 27 deletions(-) diff --git a/litellm/llms/cloro/search/transformation.py b/litellm/llms/cloro/search/transformation.py index ccf6089d1fc..113a1ad0a87 100644 --- a/litellm/llms/cloro/search/transformation.py +++ b/litellm/llms/cloro/search/transformation.py @@ -28,6 +28,11 @@ _STR_LIST: Final = TypeAdapter(list[str]) CLORO_DEFAULT_COUNTRY: Final = "US" _CLORO_GOOGLE_ROUTE: Final = "v1/monitor/google" +# The cost map prices the base call: one sync results page without the AI Overview, 5 credits. +CLORO_BASE_QUERY_CREDITS: Final = 5 +# Reserved optional_params key that carries the credits cloro charged (X-Credits-Charged) to cost tracking. +CLORO_CREDITS_CHARGED_PARAM: Final = "_cloro_credits_charged" +_CREDITS_CHARGED_HEADER: Final = "X-Credits-Charged" class CloroSearchConfig(BaseSearchConfig): @@ -83,7 +88,10 @@ class CloroSearchConfig(BaseSearchConfig): domains: Final = _domain_filter(optional_params.get("search_domain_filter")) country: Final = optional_params.get("country") unified: Final = self.get_supported_perplexity_optional_params() - passthrough: Final = {k: v for k, v in optional_params.items() if k not in unified} + # The reserved credits key is dropped: a caller-supplied value would set the cost of its own request + passthrough: Final = { + k: v for k, v in optional_params.items() if k not in unified and k != CLORO_CREDITS_CHARGED_PARAM + } return { **passthrough, "query": _with_site_filters(joined_query, domains), @@ -101,7 +109,13 @@ class CloroSearchConfig(BaseSearchConfig): ``/goto`` redirect, cut to ``max_results``. Every other key of ``result`` (``peopleAlsoAsk``, ``relatedSearches``, ``ads``, and ``aioverview`` when ``include={"aioverview": True}`` was sent) -> ``SearchResponse.provider_metadata``. + The ``X-Credits-Charged`` header goes to cost tracking, so ``pages`` and the AI Overview are billed. """ + # Written also when the header is absent, so a caller-supplied value never prices the request + logging_obj.optional_params = { # rebind-ok: cost tracking reads the reported credits from here + **logging_obj.optional_params, # pyright: ignore[reportUnknownMemberType] # Logging types it as a bare dict + CLORO_CREDITS_CHARGED_PARAM: _credits_charged(raw_response.headers.get(_CREDITS_CHARGED_HEADER)), + } response_json: Final = _JSON_OBJECT.validate_python(raw_response.json()) result: Final = _JSON_OBJECT.validate_python(response_json.get("result", {})) rows: Final = _JSON_OBJECTS.validate_python(result.get("organicResults", ())) @@ -116,6 +130,23 @@ class CloroSearchConfig(BaseSearchConfig): ) +def cloro_search_cost(price_per_query: float, credits_charged: object) -> float | None: + """Cost of the credits cloro reported, at the per-credit rate of the per-query price. None when not reported.""" + if isinstance(credits_charged, bool) or not isinstance(credits_charged, int) or credits_charged < 0: + return None + return credits_charged * price_per_query / CLORO_BASE_QUERY_CREDITS + + +def _credits_charged(header: str | None) -> int | None: + if header is None: + return None + try: + credits: Final = int(header.strip()) + except ValueError: + return None + return credits if credits >= 0 else None + + def _domain_filter(raw: object) -> tuple[str, ...]: try: return tuple(_STR_LIST.validate_python(raw)) diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json index 25198b5144d..a299c5ff665 100644 --- a/litellm/model_prices_and_context_window_backup.json +++ b/litellm/model_prices_and_context_window_backup.json @@ -25412,7 +25412,7 @@ "litellm_provider": "cloro", "mode": "search", "metadata": { - "notes": "cloro Google Search, sync, one results page: 5 credits a query. Lite plan list price: $30 for 37,500 credits ($0.80 per 1,000 credits), so $0.004 a query. include.aioverview adds 2 credits a query and each extra page adds 2 credits. Larger plans price a credit lower." + "notes": "cloro Google Search, sync, one results page: 5 credits a query. Lite plan list price: $30 for 37,500 credits ($0.80 per 1,000 credits), so $0.004 a query. include.aioverview adds 2 credits a query and each extra page adds 2 credits. LiteLLM bills the X-Credits-Charged response header at this per-credit rate ($0.0008), so these add-ons reach spend; without the header it bills this per-query price. Larger plans price a credit lower." } }, "serper/search": { diff --git a/litellm/search/cost_calculator.py b/litellm/search/cost_calculator.py index 15755128136..3dd2046c7d5 100644 --- a/litellm/search/cost_calculator.py +++ b/litellm/search/cost_calculator.py @@ -116,5 +116,16 @@ def search_provider_cost_per_query( # Simple flat rate cost_per_query = float(model_info.get("input_cost_per_query") or 0.0) + if custom_llm_provider == "cloro": + from litellm.llms.cloro.search.transformation import ( + CLORO_CREDITS_CHARGED_PARAM, + cloro_search_cost, + ) + + params: Final = optional_params if optional_params is not None else EMPTY_OPTIONAL_PARAMS + reported_cost: Final = cloro_search_cost(cost_per_query, params.get(CLORO_CREDITS_CHARGED_PARAM)) + if reported_cost is not None: + return (reported_cost, 0.0) + total_cost: Final = number_of_queries * cost_per_query return (total_cost, 0.0) # (input_cost, output_cost) diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json index 25198b5144d..a299c5ff665 100644 --- a/model_prices_and_context_window.json +++ b/model_prices_and_context_window.json @@ -25412,7 +25412,7 @@ "litellm_provider": "cloro", "mode": "search", "metadata": { - "notes": "cloro Google Search, sync, one results page: 5 credits a query. Lite plan list price: $30 for 37,500 credits ($0.80 per 1,000 credits), so $0.004 a query. include.aioverview adds 2 credits a query and each extra page adds 2 credits. Larger plans price a credit lower." + "notes": "cloro Google Search, sync, one results page: 5 credits a query. Lite plan list price: $30 for 37,500 credits ($0.80 per 1,000 credits), so $0.004 a query. include.aioverview adds 2 credits a query and each extra page adds 2 credits. LiteLLM bills the X-Credits-Charged response header at this per-credit rate ($0.0008), so these add-ons reach spend; without the header it bills this per-query price. Larger plans price a credit lower." } }, "serper/search": { diff --git a/tests/unit/llms/cloro/search/test_cloro_search_transformation.py b/tests/unit/llms/cloro/search/test_cloro_search_transformation.py index 7dcb9a9d315..bfcdbb4a850 100644 --- a/tests/unit/llms/cloro/search/test_cloro_search_transformation.py +++ b/tests/unit/llms/cloro/search/test_cloro_search_transformation.py @@ -32,9 +32,12 @@ def _organic_row(position: int, link: str) -> dict[str, object]: } -def _cloro_response(rows: list[dict[str, object]], **extra: object) -> httpx.Response: +def _cloro_response( + rows: list[dict[str, object]], credits_charged: str | None = None, **extra: object +) -> httpx.Response: return httpx.Response( 200, + headers={} if credits_charged is None else {"X-Credits-Charged": credits_charged}, json={"success": True, "result": {"organicResults": rows, "peopleAlsoAsk": PEOPLE_ALSO_ASK, **extra}}, ) @@ -43,16 +46,11 @@ def _cloro_response(rows: list[dict[str, object]], **extra: object) -> httpx.Res async def test_asearch_sends_cloro_body_and_maps_results(monkeypatch): monkeypatch.setenv("CLORO_API_KEY", "test-cloro-key") monkeypatch.delenv("CLORO_API_BASE", raising=False) - mock_response: Final = MagicMock() - mock_response.status_code = 200 - mock_response.json.return_value = { - "success": True, - "result": { - "organicResults": [_organic_row(1, "https://example.com/1"), _organic_row(2, "https://example.com/2")], - "peopleAlsoAsk": PEOPLE_ALSO_ASK, - "aioverview": AI_OVERVIEW, - }, - } + mock_response: Final = _cloro_response( + [_organic_row(1, "https://example.com/1"), _organic_row(2, "https://example.com/2")], + credits_charged="7", + aioverview=AI_OVERVIEW, + ) with patch( "litellm.llms.custom_httpx.http_handler.AsyncHTTPHandler.post", @@ -80,6 +78,8 @@ async def test_asearch_sends_cloro_body_and_maps_results(monkeypatch): ("Result 2", "https://example.com/2", "Snippet 2"), ] assert response.provider_metadata == {"peopleAlsoAsk": PEOPLE_ALSO_ASK, "aioverview": AI_OVERVIEW} + per_credit: Final[float] = litellm.model_cost["cloro/search"]["input_cost_per_query"] / 5 + assert response._hidden_params["response_cost"] == pytest.approx(7 * per_credit) def test_country_defaults_to_us_because_cloro_requires_it(): @@ -144,19 +144,43 @@ def test_missing_api_key_raises(monkeypatch): CloroSearchConfig().validate_environment(headers={}) -def test_search_cost_comes_from_cost_map(monkeypatch): +def _search_cost(monkeypatch: pytest.MonkeyPatch, response: httpx.Response, **params: object) -> tuple[float, object]: + """``litellm.search`` against a mocked cloro response: (response cost, JSON body sent to cloro).""" monkeypatch.setenv("CLORO_API_KEY", "test-cloro-key") + with patch("litellm.llms.custom_httpx.http_handler.HTTPHandler.post", return_value=response) as mock_post: + result: Final = litellm.search(query="litellm", search_provider="cloro", **params) + return result._hidden_params["response_cost"], mock_post.call_args.kwargs["json"] + + +def test_search_cost_comes_from_cost_map(monkeypatch): priced: Final[float] = litellm.model_cost["cloro/search"]["input_cost_per_query"] assert priced > 0 - mock_response: Final = MagicMock() - mock_response.status_code = 200 - mock_response.json.return_value = { - "success": True, - "result": {"organicResults": [_organic_row(1, "https://example.com/1")]}, - } - with patch( - "litellm.llms.custom_httpx.http_handler.HTTPHandler.post", - return_value=mock_response, - ): - response: Final = litellm.search(query="litellm", search_provider="cloro") - assert response._hidden_params["response_cost"] == pytest.approx(priced) + cost, _ = _search_cost(monkeypatch, _cloro_response([_organic_row(1, "https://example.com/1")])) + assert cost == pytest.approx(priced) + + +@pytest.mark.parametrize( + ("credits_charged", "expected_credits"), + [("9", 9), ("7", 7), ("5", 5), ("0", 0), (None, 5), ("not-a-number", 5), ("-3", 5), ("7.5", 5)], +) +def test_search_cost_bills_the_credits_cloro_charged(monkeypatch, credits_charged, expected_credits): + """``X-Credits-Charged`` is billed at the cost map's per-credit rate (5 credits = one query), so + ``pages`` and ``include.aioverview`` reach spend. Without a valid header the per-query price applies.""" + per_credit: Final[float] = litellm.model_cost["cloro/search"]["input_cost_per_query"] / 5 + cost, body = _search_cost( + monkeypatch, + _cloro_response([_organic_row(1, "https://example.com/1")], credits_charged=credits_charged), + pages=2, + include={"aioverview": True}, + ) + assert body == {"query": "litellm", "country": "US", "pages": 2, "include": {"aioverview": True}} + assert cost == pytest.approx(expected_credits * per_credit) + + +def test_caller_cannot_set_the_reported_credits(monkeypatch): + priced: Final[float] = litellm.model_cost["cloro/search"]["input_cost_per_query"] + cost, body = _search_cost( + monkeypatch, _cloro_response([_organic_row(1, "https://example.com/1")]), _cloro_credits_charged=0 + ) + assert "_cloro_credits_charged" not in body + assert cost == pytest.approx(priced) From 9aec65f5101b398c34e14fb67be4be64fc890ec0 Mon Sep 17 00:00:00 2001 From: Ricardo Batista <138892976+rbatista191@users.noreply.github.com> Date: Fri, 6 Nov 2026 15:36:03 +0100 Subject: [PATCH 3/3] fix(search): send excluded cloro domains as -site: terms A leading '-' in search_domain_filter excludes a domain. It was sent as site:-example.com. Excluded domains are now separate -site: terms; included domains stay joined with OR. --- litellm/llms/cloro/search/transformation.py | 13 ++++++++++--- .../search/test_cloro_search_transformation.py | 15 +++++++++++++++ 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/litellm/llms/cloro/search/transformation.py b/litellm/llms/cloro/search/transformation.py index 113a1ad0a87..c0c67be2efb 100644 --- a/litellm/llms/cloro/search/transformation.py +++ b/litellm/llms/cloro/search/transformation.py @@ -78,7 +78,7 @@ class CloroSearchConfig(BaseSearchConfig): ) -> dict[str, object]: # mutable-ok: the http handler sends this as the JSON body """ Unified params -> cloro body: ``query`` (list joined with spaces, ``search_domain_filter`` - folded in as ``site:`` operators), ``country`` upper-cased and sent as ``US`` when absent, + folded in as ``site:`` and ``-site:`` operators), ``country`` upper-cased and sent as ``US`` when absent, because cloro requires it. ``max_results`` has no cloro equivalent: one call returns one Google results page, and the response is cut to ``max_results``. ``max_tokens_per_page`` is dropped. Everything outside the unified spec (``include``, ``device``, ``location``, @@ -155,10 +155,17 @@ def _domain_filter(raw: object) -> tuple[str, ...]: def _with_site_filters(query: str, domains: tuple[str, ...]) -> str: + """A leading ``-`` excludes a domain, as in Perplexity's ``search_domain_filter``. Included + domains are joined with ``OR``; each excluded domain is a separate ``-site:`` term.""" if not domains: return query - site_clause: Final = " OR ".join(f"site:{domain}" for domain in domains) - return f"({query}) ({site_clause})" + included: Final = [d for d in domains if not d.startswith("-")] + excluded: Final = [d[1:] for d in domains if d.startswith("-") and len(d) > 1] + clauses: Final = [f"({query})"] + if included: + clauses.append("(" + " OR ".join(f"site:{d}" for d in included) + ")") + clauses.extend(f"-site:{d}" for d in excluded) + return " ".join(clauses) def _max_results(optional_params: object) -> int | None: diff --git a/tests/unit/llms/cloro/search/test_cloro_search_transformation.py b/tests/unit/llms/cloro/search/test_cloro_search_transformation.py index bfcdbb4a850..c130c53c4aa 100644 --- a/tests/unit/llms/cloro/search/test_cloro_search_transformation.py +++ b/tests/unit/llms/cloro/search/test_cloro_search_transformation.py @@ -82,6 +82,21 @@ async def test_asearch_sends_cloro_body_and_maps_results(monkeypatch): assert response._hidden_params["response_cost"] == pytest.approx(7 * per_credit) +@pytest.mark.parametrize( + ("domains", "expected_query"), + [ + (["-example.com"], "(q) -site:example.com"), + (["-a.com", "-b.com"], "(q) -site:a.com -site:b.com"), + (["a.com", "b.com", "-c.com"], "(q) (site:a.com OR site:b.com) -site:c.com"), + ], +) +def test_excluded_domains_become_negative_site_terms(domains: list[str], expected_query: str): + body: Final = CloroSearchConfig().transform_search_request( + query="q", optional_params={"search_domain_filter": domains} + ) + assert body["query"] == expected_query + + def test_country_defaults_to_us_because_cloro_requires_it(): body: Final = CloroSearchConfig().transform_search_request(query=["rank", "tracker"], optional_params={}) assert body == {"query": "rank tracker", "country": "US"}