diff --git a/.github/workflows/test-unit.yml b/.github/workflows/test-unit.yml index fb29a92e306..87a967becec 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..c0c67be2efb --- /dev/null +++ b/litellm/llms/cloro/search/transformation.py @@ -0,0 +1,204 @@ +""" +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" +# 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): + 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:`` 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``, + ``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() + # 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), + "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``. + 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", ())) + 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 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)) + except ValidationError: + return () + + +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 + 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: + 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 77244a32f6f..d12c94ef852 100644 --- a/litellm/model_prices_and_context_window_backup.json +++ b/litellm/model_prices_and_context_window_backup.json @@ -25435,6 +25435,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. 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": { "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/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/litellm/types/utils.py b/litellm/types/utils.py index 3ddeb118c33..ecef783331d 100644 --- a/litellm/types/utils.py +++ b/litellm/types/utils.py @@ -4856,6 +4856,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 5ec089a106a..1c51bada32f 100644 --- a/litellm/utils.py +++ b/litellm/utils.py @@ -11466,6 +11466,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 @@ -11510,6 +11511,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 77244a32f6f..d12c94ef852 100644 --- a/model_prices_and_context_window.json +++ b/model_prices_and_context_window.json @@ -25435,6 +25435,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. 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": { "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..c130c53c4aa --- /dev/null +++ b/tests/unit/llms/cloro/search/test_cloro_search_transformation.py @@ -0,0 +1,201 @@ +""" +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]], 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}}, + ) + + +@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 = _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", + 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} + 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) + + +@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"} + + +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 _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 + 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)