This commit is contained in:
Ricardo Batista 2026-11-07 02:52:29 +00:00 • committed by GitHub
commit 5689c54f66
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 499 additions and 0 deletions

View file

@ -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

View file

@ -0,0 +1,7 @@
"""
cloro Search API module.
"""
from litellm.llms.cloro.search.transformation import CloroSearchConfig
__all__ = ["CloroSearchConfig"]

View file

@ -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 ""

View file

@ -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",

View file

@ -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",

View file

@ -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)

View file

@ -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

View file

@ -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:

View file

@ -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",

View file

@ -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",

View file

@ -21,6 +21,7 @@ SEARCH_PROVIDERS = [
"apiserpent",
"tinyfish",
"nimble",
"cloro",
]
ALLOWED_FILES_IN_LLMS_FOLDER = [

View file

@ -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)

View file

View file

View file

@ -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)