openserp 0.1.0__py3-none-any.whl

openserp/__init__.py

@@ -0,0 +1,66 @@
+from .client import AsyncOpenSERP, OpenSERP
+from .errors import (
+    CaptchaError,
+    CloudOnlyError,
+    OssOnlyError,
+    RateLimitError,
+    SERPError,
+    TimeoutError,
+)
+from .models import (
+    Backend,
+    CircuitBreakerStatsResponse,
+    CloudAccount,
+    CreditInfo,
+    Engine,
+    EnginesCapabilities,
+    EnginesStatus,
+    HealthStatus,
+    ImageEnvelope,
+    ImageResult,
+    LastResponse,
+    MegaEnginesResponse,
+    MegaMode,
+    MegaSearchEnvelope,
+    Pricing,
+    ProxyStats,
+    ReadinessStatus,
+    ResponseFormat,
+    SearchEnvelope,
+    SearchResult,
+    StatsResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncOpenSERP",
+    "Backend",
+    "CaptchaError",
+    "CircuitBreakerStatsResponse",
+    "CloudAccount",
+    "CloudOnlyError",
+    "CreditInfo",
+    "Engine",
+    "EnginesCapabilities",
+    "EnginesStatus",
+    "HealthStatus",
+    "ImageEnvelope",
+    "ImageResult",
+    "LastResponse",
+    "MegaEnginesResponse",
+    "MegaMode",
+    "MegaSearchEnvelope",
+    "OpenSERP",
+    "OssOnlyError",
+    "Pricing",
+    "ProxyStats",
+    "RateLimitError",
+    "ReadinessStatus",
+    "ResponseFormat",
+    "SERPError",
+    "SearchEnvelope",
+    "SearchResult",
+    "StatsResponse",
+    "TimeoutError",
+]

openserp/backend.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from .models import Backend
+
+OSS_BASE_URL = "http://localhost:7000"
+CLOUD_BASE_URL = "https://api.openserp.org/v1"
+
+
+def normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+def resolve_base_url(api_key: str | None = None, base_url: str | None = None) -> str:
+    if base_url:
+        return normalize_base_url(base_url)
+    if api_key:
+        return CLOUD_BASE_URL
+    return OSS_BASE_URL
+
+
+def infer_backend(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    backend: Backend | None = None,
+) -> Backend:
+    if backend:
+        return backend
+
+    if base_url:
+        try:
+            if urlparse(base_url).hostname == "api.openserp.org":
+                return "cloud"
+        except ValueError:
+            if "api.openserp.org" in base_url:
+                return "cloud"
+
+    if api_key:
+        return "cloud"
+
+    return "oss"

openserp/client.py

@@ -0,0 +1,534 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar, cast
+
+import httpx
+from pydantic import BaseModel
+
+from .backend import infer_backend, resolve_base_url
+from .errors import CloudOnlyError, OssOnlyError, TimeoutError, error_from_response
+from .models import (
+    Backend,
+    CacheStats,
+    CircuitBreakerStatsResponse,
+    CloudAccount,
+    CreditInfo,
+    Engine,
+    EnginesCapabilities,
+    EnginesStatus,
+    HealthStatus,
+    ImageEnvelope,
+    LastResponse,
+    MegaEnginesResponse,
+    MegaSearchEnvelope,
+    Pricing,
+    ProxyStats,
+    ReadinessStatus,
+    ResponseFormat,
+    SearchEnvelope,
+    StatsResponse,
+)
+
+QueryValue = str | int | float | bool | list[str] | tuple[str, ...] | None
+RetryHook = Callable[[Exception, int], bool]
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+_PROXY_HEADER_MAP: dict[str, str] = {
+    "use_proxy": "X-Use-Proxy",
+    "proxy_url": "X-Proxy-URL",
+    "proxy_country": "X-Proxy-Country",
+    "proxy_class": "X-Proxy-Class",
+    "proxy_provider": "X-Proxy-Provider",
+    "proxy_session_id": "X-Proxy-Session-ID",
+    "tenant": "X-Tenant",
+}
+
+
+class _BaseOpenSERP:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        backend: Backend | None = None,
+        timeout: float = 30.0,
+        headers: Mapping[str, str] | None = None,
+        retry: RetryHook | None = None,
+    ) -> None:
+        self.api_key = api_key
+        self._base_url = resolve_base_url(api_key=api_key, base_url=base_url)
+        self._backend = infer_backend(api_key=api_key, base_url=base_url, backend=backend)
+        self.timeout = timeout
+        self.headers = dict(headers or {})
+        self.retry = retry
+        self.last_response: LastResponse | None = None
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def backend(self) -> Backend:
+        return self._backend
+
+    def _assert_cloud(self, method: str) -> None:
+        if self.backend != "cloud":
+            raise CloudOnlyError(method)
+
+    def _assert_oss(self, method: str) -> None:
+        if self.backend != "oss":
+            raise OssOnlyError(method)
+
+    def _merged_headers(self, headers: Mapping[str, str] | None = None) -> dict[str, str]:
+        merged = dict(self.headers)
+        if self.api_key:
+            merged["Authorization"] = f"Bearer {self.api_key}"
+        if headers:
+            merged.update(headers)
+        return merged
+
+    def _build_search_request(
+        self,
+        params: Mapping[str, Any],
+    ) -> tuple[dict[str, QueryValue], dict[str, str], ResponseFormat | None]:
+        engines = params.get("engines")
+        query: dict[str, QueryValue] = {**params}
+        if engines is not None:
+            query["engines"] = list(engines)
+        clean_query, headers = _split_query_and_headers(query)
+        return clean_query, headers, cast(ResponseFormat | None, params.get("format"))
+
+    def _build_parse_request(
+        self, format: ResponseFormat | None
+    ) -> tuple[dict[str, QueryValue] | None, dict[str, str]]:
+        query: dict[str, QueryValue] | None = {"format": format} if format else None
+        return query, {"Content-Type": "text/html; charset=utf-8"}
+
+    def _set_last_response(self, response: httpx.Response) -> None:
+        headers = {key.lower(): value for key, value in response.headers.items()}
+        credits_used = _int_header(response.headers, "x-credits-used")
+        credits_remaining = _int_header(response.headers, "x-credits-remaining")
+        credits = (
+            CreditInfo(used=credits_used, remaining=credits_remaining)
+            if credits_used is not None or credits_remaining is not None
+            else None
+        )
+        self.last_response = LastResponse(
+            status=response.status_code,
+            request_id=response.headers.get("x-request-id"),
+            credits=credits,
+            engine_used=response.headers.get("x-engine-used"),
+            fallback_engine=response.headers.get("x-fallback-engine"),
+            cache=response.headers.get("x-cache"),
+            proxy_mode=response.headers.get("x-proxy-mode"),
+            proxy_tag=response.headers.get("x-proxy-tag"),
+            proxy_used=response.headers.get("x-proxy-used"),
+            network_bytes=_int_header(response.headers, "x-network-bytes"),
+            browser_profile_id=response.headers.get("x-browser-profile-id"),
+            headers=headers,
+        )
+
+    def _handle_response(self, response: httpx.Response, format: ResponseFormat | None) -> Any:
+        self._set_last_response(response)
+        body = _read_body(response, format)
+        if response.is_error:
+            raise error_from_response(
+                response.status_code, body, response.headers.get("x-request-id")
+            )
+        return body
+
+
+class OpenSERP(_BaseOpenSERP):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        backend: Backend | None = None,
+        timeout: float = 30.0,
+        headers: Mapping[str, str] | None = None,
+        retry: RetryHook | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            backend=backend,
+            timeout=timeout,
+            headers=headers,
+            retry=retry,
+        )
+        self._client = client or httpx.Client(timeout=timeout)
+        self._owns_client = client is None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> OpenSERP:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def search(self, *, engine: Engine, **params: Any) -> SearchEnvelope | str:
+        query, headers, format = self._build_search_request(params)
+        return self._get_model(SearchEnvelope, f"/{engine}/search", query, headers, format)
+
+    def image(self, *, engine: Engine, **params: Any) -> ImageEnvelope | str:
+        query, headers, format = self._build_search_request(params)
+        return self._get_model(ImageEnvelope, f"/{engine}/image", query, headers, format)
+
+    def mega_search(self, **params: Any) -> MegaSearchEnvelope | str:
+        query, headers, format = self._build_search_request(params)
+        return self._get_model(MegaSearchEnvelope, "/mega/search", query, headers, format)
+
+    def fast_search(self, **params: Any) -> MegaSearchEnvelope | str:
+        return self.mega_search(**{**params, "mode": "fast"})
+
+    def any_search(self, **params: Any) -> MegaSearchEnvelope | str:
+        return self.mega_search(**{**params, "mode": "any"})
+
+    def mega_image(self, **params: Any) -> ImageEnvelope | str:
+        query, headers, format = self._build_search_request(params)
+        return self._get_model(ImageEnvelope, "/mega/image", query, headers, format)
+
+    def fast_image(self, **params: Any) -> ImageEnvelope | str:
+        return self.mega_image(**{**params, "mode": "fast"})
+
+    def any_image(self, **params: Any) -> ImageEnvelope | str:
+        return self.mega_image(**{**params, "mode": "any"})
+
+    def parse_google(
+        self, *, html: str, format: ResponseFormat | None = None
+    ) -> SearchEnvelope | str:
+        self._assert_oss("parse_google")
+        return self._parse("/google/parse", html, format)
+
+    def parse_bing(
+        self, *, html: str, format: ResponseFormat | None = None
+    ) -> SearchEnvelope | str:
+        self._assert_oss("parse_bing")
+        return self._parse("/bing/parse", html, format)
+
+    def health(self) -> HealthStatus:
+        self._assert_oss("health")
+        return self._get_json(HealthStatus, "/health")
+
+    def ready(self) -> ReadinessStatus:
+        self._assert_oss("ready")
+        return self._get_json(ReadinessStatus, "/ready")
+
+    def stats(self) -> StatsResponse:
+        self._assert_oss("stats")
+        return self._get_json(StatsResponse, "/stats")
+
+    def cache_stats(self) -> CacheStats:
+        self._assert_oss("cache_stats")
+        return self._get_json(CacheStats, "/stats/cache")
+
+    def proxy_stats(self) -> ProxyStats:
+        self._assert_oss("proxy_stats")
+        return self._get_json(ProxyStats, "/stats/proxy")
+
+    def circuit_breaker_stats(self) -> CircuitBreakerStatsResponse:
+        self._assert_oss("circuit_breaker_stats")
+        return self._get_json(CircuitBreakerStatsResponse, "/stats/cb")
+
+    def engines(self) -> MegaEnginesResponse:
+        self._assert_oss("engines")
+        return self._get_json(MegaEnginesResponse, "/mega/engines")
+
+    def me(self) -> CloudAccount:
+        self._assert_cloud("me")
+        return self._get_json(CloudAccount, "/me")
+
+    def pricing(self) -> Pricing:
+        self._assert_cloud("pricing")
+        return self._get_json(Pricing, "/pricing")
+
+    def engines_status(self) -> EnginesStatus:
+        self._assert_cloud("engines_status")
+        return self._get_json(EnginesStatus, "/engines/status")
+
+    def engines_capabilities(self) -> EnginesCapabilities:
+        self._assert_cloud("engines_capabilities")
+        return self._get_json(EnginesCapabilities, "/engines/capabilities")
+
+    def _get_json(self, model: type[ModelT], path: str) -> ModelT:
+        body = self._send("GET", path)
+        return model.model_validate(body)
+
+    def _parse(self, path: str, html: str, format: ResponseFormat | None) -> SearchEnvelope | str:
+        query, headers = self._build_parse_request(format)
+        body = self._send("POST", path, query=query, headers=headers, content=html, format=format)
+        return body if isinstance(body, str) else SearchEnvelope.model_validate(body)
+
+    def _get_model(
+        self,
+        model: type[ModelT],
+        path: str,
+        query: Mapping[str, QueryValue] | None = None,
+        headers: Mapping[str, str] | None = None,
+        format: ResponseFormat | None = None,
+    ) -> ModelT | str:
+        body = self._send("GET", path, query=query, headers=headers, format=format)
+        return body if isinstance(body, str) else model.model_validate(body)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, QueryValue] | None = None,
+        headers: Mapping[str, str] | None = None,
+        format: ResponseFormat | None = None,
+        content: str | None = None,
+    ) -> Any:
+        attempt = 0
+        while True:
+            try:
+                try:
+                    response = self._client.request(
+                        method,
+                        f"{self.base_url}{path}",
+                        params=_encode_query(query),
+                        headers=self._merged_headers(headers),
+                        content=content,
+                    )
+                except httpx.TimeoutException as exc:
+                    raise TimeoutError(self.timeout) from exc
+                return self._handle_response(response, format)
+            except Exception as exc:
+                if not self.retry or not self.retry(exc, attempt):
+                    raise
+                attempt += 1
+
+
+class AsyncOpenSERP(_BaseOpenSERP):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        backend: Backend | None = None,
+        timeout: float = 30.0,
+        headers: Mapping[str, str] | None = None,
+        retry: RetryHook | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            backend=backend,
+            timeout=timeout,
+            headers=headers,
+            retry=retry,
+        )
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = client is None
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncOpenSERP:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()
+
+    async def search(self, *, engine: Engine, **params: Any) -> SearchEnvelope | str:
+        query, headers, format = self._build_search_request(params)
+        return await self._get_model(SearchEnvelope, f"/{engine}/search", query, headers, format)
+
+    async def image(self, *, engine: Engine, **params: Any) -> ImageEnvelope | str:
+        query, headers, format = self._build_search_request(params)
+        return await self._get_model(ImageEnvelope, f"/{engine}/image", query, headers, format)
+
+    async def mega_search(self, **params: Any) -> MegaSearchEnvelope | str:
+        query, headers, format = self._build_search_request(params)
+        return await self._get_model(MegaSearchEnvelope, "/mega/search", query, headers, format)
+
+    async def fast_search(self, **params: Any) -> MegaSearchEnvelope | str:
+        return await self.mega_search(**{**params, "mode": "fast"})
+
+    async def any_search(self, **params: Any) -> MegaSearchEnvelope | str:
+        return await self.mega_search(**{**params, "mode": "any"})
+
+    async def mega_image(self, **params: Any) -> ImageEnvelope | str:
+        query, headers, format = self._build_search_request(params)
+        return await self._get_model(ImageEnvelope, "/mega/image", query, headers, format)
+
+    async def fast_image(self, **params: Any) -> ImageEnvelope | str:
+        return await self.mega_image(**{**params, "mode": "fast"})
+
+    async def any_image(self, **params: Any) -> ImageEnvelope | str:
+        return await self.mega_image(**{**params, "mode": "any"})
+
+    async def parse_google(
+        self, *, html: str, format: ResponseFormat | None = None
+    ) -> SearchEnvelope | str:
+        self._assert_oss("parse_google")
+        return await self._parse("/google/parse", html, format)
+
+    async def parse_bing(
+        self, *, html: str, format: ResponseFormat | None = None
+    ) -> SearchEnvelope | str:
+        self._assert_oss("parse_bing")
+        return await self._parse("/bing/parse", html, format)
+
+    async def health(self) -> HealthStatus:
+        self._assert_oss("health")
+        return await self._get_json(HealthStatus, "/health")
+
+    async def ready(self) -> ReadinessStatus:
+        self._assert_oss("ready")
+        return await self._get_json(ReadinessStatus, "/ready")
+
+    async def stats(self) -> StatsResponse:
+        self._assert_oss("stats")
+        return await self._get_json(StatsResponse, "/stats")
+
+    async def cache_stats(self) -> CacheStats:
+        self._assert_oss("cache_stats")
+        return await self._get_json(CacheStats, "/stats/cache")
+
+    async def proxy_stats(self) -> ProxyStats:
+        self._assert_oss("proxy_stats")
+        return await self._get_json(ProxyStats, "/stats/proxy")
+
+    async def circuit_breaker_stats(self) -> CircuitBreakerStatsResponse:
+        self._assert_oss("circuit_breaker_stats")
+        return await self._get_json(CircuitBreakerStatsResponse, "/stats/cb")
+
+    async def engines(self) -> MegaEnginesResponse:
+        self._assert_oss("engines")
+        return await self._get_json(MegaEnginesResponse, "/mega/engines")
+
+    async def me(self) -> CloudAccount:
+        self._assert_cloud("me")
+        return await self._get_json(CloudAccount, "/me")
+
+    async def pricing(self) -> Pricing:
+        self._assert_cloud("pricing")
+        return await self._get_json(Pricing, "/pricing")
+
+    async def engines_status(self) -> EnginesStatus:
+        self._assert_cloud("engines_status")
+        return await self._get_json(EnginesStatus, "/engines/status")
+
+    async def engines_capabilities(self) -> EnginesCapabilities:
+        self._assert_cloud("engines_capabilities")
+        return await self._get_json(EnginesCapabilities, "/engines/capabilities")
+
+    async def _get_json(self, model: type[ModelT], path: str) -> ModelT:
+        body = await self._send("GET", path)
+        return model.model_validate(body)
+
+    async def _parse(
+        self, path: str, html: str, format: ResponseFormat | None
+    ) -> SearchEnvelope | str:
+        query, headers = self._build_parse_request(format)
+        body = await self._send(
+            "POST", path, query=query, headers=headers, content=html, format=format
+        )
+        return body if isinstance(body, str) else SearchEnvelope.model_validate(body)
+
+    async def _get_model(
+        self,
+        model: type[ModelT],
+        path: str,
+        query: Mapping[str, QueryValue] | None = None,
+        headers: Mapping[str, str] | None = None,
+        format: ResponseFormat | None = None,
+    ) -> ModelT | str:
+        body = await self._send("GET", path, query=query, headers=headers, format=format)
+        return body if isinstance(body, str) else model.model_validate(body)
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, QueryValue] | None = None,
+        headers: Mapping[str, str] | None = None,
+        format: ResponseFormat | None = None,
+        content: str | None = None,
+    ) -> Any:
+        attempt = 0
+        while True:
+            try:
+                try:
+                    response = await self._client.request(
+                        method,
+                        f"{self.base_url}{path}",
+                        params=_encode_query(query),
+                        headers=self._merged_headers(headers),
+                        content=content,
+                    )
+                except httpx.TimeoutException as exc:
+                    raise TimeoutError(self.timeout) from exc
+                return self._handle_response(response, format)
+            except Exception as exc:
+                if not self.retry or not self.retry(exc, attempt):
+                    raise
+                attempt += 1
+
+
+def _split_query_and_headers(
+    query: Mapping[str, QueryValue],
+) -> tuple[dict[str, QueryValue], dict[str, str]]:
+    clean_query: dict[str, QueryValue] = {}
+    headers: dict[str, str] = {}
+    for key, value in query.items():
+        if value is None:
+            continue
+        header_name = _PROXY_HEADER_MAP.get(key)
+        if header_name is not None:
+            headers[header_name] = _encode_value(value)
+        else:
+            clean_query[key] = value
+    return clean_query, headers
+
+
+def _encode_query(query: Mapping[str, QueryValue] | None) -> dict[str, str]:
+    if not query:
+        return {}
+    return {key: _encode_value(value) for key, value in query.items() if value is not None}
+
+
+def _encode_value(value: QueryValue) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, list | tuple):
+        return ",".join(str(item) for item in value)
+    return str(value)
+
+
+def _read_body(response: httpx.Response, format: ResponseFormat | None = None) -> Any:
+    if response.status_code == 204:
+        return None
+    if format and format != "json":
+        return response.text
+    content_type = response.headers.get("content-type", "")
+    if "application/json" in content_type:
+        return response.json()
+    text = response.text
+    if not text:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return text
+
+
+def _int_header(headers: httpx.Headers, name: str) -> int | None:
+    value = headers.get(name)
+    if value is None or value == "":
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None

openserp/errors.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class SERPError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str | None = None,
+        reason: str | None = None,
+        request_id: str | None = None,
+        meta: dict[str, Any] | None = None,
+        response: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.reason = reason
+        self.request_id = request_id
+        self.meta = meta
+        self.response = response
+
+
+class RateLimitError(SERPError):
+    pass
+
+
+class CaptchaError(SERPError):
+    pass
+
+
+class CloudOnlyError(SERPError):
+    def __init__(self, method: str) -> None:
+        super().__init__(
+            f"{method} is only available against OpenSERP Cloud. "
+            "Configure api_key/base_url for https://api.openserp.org/v1 "
+            'or set backend="cloud".'
+        )
+
+
+class OssOnlyError(SERPError):
+    def __init__(self, method: str) -> None:
+        super().__init__(
+            f"{method} is only available against a self-hosted OpenSERP server. "
+            'Configure base_url for your OSS server or set backend="oss".'
+        )
+
+
+class TimeoutError(SERPError):
+    def __init__(self, timeout: float) -> None:
+        super().__init__(
+            f"OpenSERP request timed out after {timeout:g}s",
+            code="request_timeout",
+        )
+
+
+def error_from_response(
+    status: int,
+    body: Any,
+    request_id: str | None = None,
+) -> SERPError:
+    data = body if isinstance(body, dict) else {}
+    code = data.get("error")
+    message = data.get("message") or f"OpenSERP request failed with status {status}"
+    options = {
+        "status": status,
+        "code": code,
+        "reason": data.get("reason"),
+        "request_id": data.get("request_id") or request_id,
+        "meta": data.get("meta"),
+        "response": body,
+    }
+
+    if status == 429 or code == "rate_limited":
+        return RateLimitError(message, **options)
+
+    if code == "captcha_detected":
+        return CaptchaError(message, **options)
+
+    return SERPError(message, **options)

openserp/models.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Backend = Literal["oss", "cloud"]
+Engine = Literal["google", "yandex", "baidu", "bing", "duck", "duckduckgo", "ecosia"]
+MegaMode = Literal["balanced", "any", "fast"]
+ResponseFormat = Literal["json", "markdown", "text", "ndjson"]
+
+
+class OpenSERPModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="json")
+
+
+class CreditInfo(OpenSERPModel):
+    used: int | None = None
+    remaining: int | None = None
+
+
+class LastResponse(OpenSERPModel):
+    status: int
+    request_id: str | None = None
+    credits: CreditInfo | None = None
+    engine_used: str | None = None
+    fallback_engine: str | None = None
+    cache: str | None = None
+    proxy_mode: str | None = None
+    proxy_tag: str | None = None
+    proxy_used: str | None = None
+    network_bytes: int | None = None
+    browser_profile_id: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+
+
+class QueryEcho(OpenSERPModel):
+    text: str | None = None
+    lang: str | None = None
+    region: str | None = None
+    engines_requested: list[str] = Field(default_factory=list)
+
+
+class EngineErrorDetail(OpenSERPModel):
+    engine: str
+    error: str
+    message: str | None = None
+
+
+class ResponseMeta(OpenSERPModel):
+    request_id: str | None = None
+    requested_at: str | None = None
+    took_ms: int | None = None
+    engines_failed: list[str] = Field(default_factory=list)
+    engine_errors: list[EngineErrorDetail] | None = None
+    version: str | None = None
+
+
+class Pagination(OpenSERPModel):
+    page: int | None = None
+    has_more: bool | None = None
+    next_start: int | None = None
+
+
+class Position(OpenSERPModel):
+    absolute: int | None = None
+
+
+class DomainInfo(OpenSERPModel):
+    tld: str | None = None
+    sld: str | None = None
+    category: str | None = None
+
+
+class Classification(OpenSERPModel):
+    content_type: str | None = None
+    source_hint: str | None = None
+
+
+class SearchResult(OpenSERPModel):
+    id: str | None = None
+    rank: int | None = None
+    type: str | None = None
+    title: str | None = None
+    url: str | None = None
+    display_url: str | None = None
+    snippet: str | None = None
+    domain: str | None = None
+    favicon: str | None = None
+    position: Position | None = None
+    engine: str | None = None
+    domain_info: DomainInfo | None = None
+    classification: Classification | None = None
+
+
+class ImageData(OpenSERPModel):
+    url: str | None = None
+    thumbnail: str | None = None
+    width: int | None = None
+    height: int | None = None
+
+
+class ImageSource(OpenSERPModel):
+    page_url: str | None = None
+    domain: str | None = None
+
+
+class ImageResult(OpenSERPModel):
+    id: str | None = None
+    rank: int | None = None
+    type: str | None = None
+    title: str | None = None
+    image: ImageData | None = None
+    source: ImageSource | None = None
+    engine: str | None = None
+
+
+class ClusterOccurrence(OpenSERPModel):
+    engine: str | None = None
+    rank: int | None = None
+    result_id: str | None = None
+
+
+class Cluster(OpenSERPModel):
+    id: str | None = None
+    canonical_url: str | None = None
+    domain: str | None = None
+    title: str | None = None
+    occurrences: list[ClusterOccurrence] = Field(default_factory=list)
+    engines_count: int | None = None
+    best_rank: int | None = None
+    score: float | None = None
+
+
+class Envelope(OpenSERPModel):
+    query: QueryEcho | None = None
+    meta: ResponseMeta | None = None
+    pagination: Pagination | None = None
+    credits: CreditInfo | None = None
+
+    def to_pandas(self) -> Any:
+        try:
+            import pandas as pd  # type: ignore[import-untyped]
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError("Install pandas support with: pip install openserp[pandas]") from exc
+
+        return pd.DataFrame(self._result_records())
+
+    def _result_records(self) -> list[dict[str, Any]]:
+        raise NotImplementedError
+
+
+class SearchEnvelope(Envelope):
+    results: list[SearchResult] = Field(default_factory=list)
+
+    def _result_records(self) -> list[dict[str, Any]]:
+        records: list[dict[str, Any]] = []
+        for item in self.results:
+            record = item.model_dump(mode="json")
+            if item.position:
+                record["position_absolute"] = item.position.absolute
+            records.append(record)
+        return records
+
+
+class MegaSearchEnvelope(SearchEnvelope):
+    clusters: list[Cluster] | None = None
+
+
+class ImageEnvelope(Envelope):
+    results: list[ImageResult] = Field(default_factory=list)
+
+    def _result_records(self) -> list[dict[str, Any]]:
+        records: list[dict[str, Any]] = []
+        for item in self.results:
+            record = item.model_dump(mode="json")
+            if item.image:
+                record["image_url"] = item.image.url
+                record["thumbnail"] = item.image.thumbnail
+                record["width"] = item.image.width
+                record["height"] = item.image.height
+            if item.source:
+                record["page_url"] = item.source.page_url
+                record["domain"] = item.source.domain
+            records.append(record)
+        return records
+
+
+class ErrorResponse(OpenSERPModel):
+    error: str
+    code: int
+    request_id: str | None = None
+    message: str | None = None
+    reason: str | None = None
+    meta: dict[str, Any] | None = None
+
+
+class EngineHealth(OpenSERPModel):
+    name: str
+    initialized: bool
+    status: str
+
+
+class HealthStatus(OpenSERPModel):
+    status: str
+    uptime: str | None = None
+    engines: list[EngineHealth] = Field(default_factory=list)
+    system: dict[str, Any] = Field(default_factory=dict)
+
+
+class ReadinessStatus(OpenSERPModel):
+    status: str
+
+
+class CacheStats(OpenSERPModel):
+    status: bool
+    entries: int | None = None
+    hits: int | None = None
+    misses: int | None = None
+    bypasses: int | None = None
+    evictions: int | None = None
+    ttl_seconds: int | None = None
+    max_size: int | None = None
+
+
+class ProxyStats(OpenSERPModel):
+    configured_count: int | None = None
+    healthy_count: int | None = None
+    unhealthy_count: int | None = None
+    request_proxy_url_enabled: bool | None = None
+    lanes: dict[str, Any] | None = None
+    browser_processes: dict[str, Any] | None = None
+    tags: dict[str, Any] = Field(default_factory=dict)
+    entries: list[dict[str, Any]] = Field(default_factory=list)
+    engines: dict[str, Any] | None = None
+
+
+class CircuitBreakerStat(OpenSERPModel):
+    engine: str
+    state: str
+    failure_count: int
+    last_changed: str
+    retry_in: int | None = None
+    avg_response_ms: int | None = None
+
+
+class CircuitBreakerStatsResponse(OpenSERPModel):
+    circuit_breakers: list[CircuitBreakerStat] = Field(default_factory=list)
+
+
+class StatsResponse(CircuitBreakerStatsResponse):
+    cache: CacheStats
+    proxy: ProxyStats
+
+
+class MegaEngineInfo(OpenSERPModel):
+    name: str
+    initialized: bool
+    circuit_state: str | None = None
+
+
+class MegaEnginesResponse(OpenSERPModel):
+    engines: list[MegaEngineInfo] = Field(default_factory=list)
+    total: int
+
+
+class CloudAccount(OpenSERPModel):
+    id: str | None = None
+    email: str | None = None
+    created_at: str | None = None
+    credits_remaining: int | None = None
+    plan: str | None = None
+
+
+class Price(OpenSERPModel):
+    credits: int | None = None
+    price_usd: float | None = None
+
+
+class Pricing(OpenSERPModel):
+    credit_price_usd: float | None = None
+    search: Price | None = None
+    mega_search: Price | None = None
+    image_search: Price | None = None
+    any_search: Price | None = None
+    fast_search: Price | None = None
+    any_image: Price | None = None
+    fast_image: Price | None = None
+
+
+class EngineStatus(OpenSERPModel):
+    status: str | None = None
+    latency_ms: int | None = None
+
+
+class EnginesStatus(OpenSERPModel):
+    overall: str | None = None
+    engines: dict[str, EngineStatus] | None = None
+
+
+class EngineCapability(OpenSERPModel):
+    web: bool | None = None
+    image: bool | None = None
+    fallback_web: bool | None = None
+    fallback_image: bool | None = None
+
+
+class ModeCapability(OpenSERPModel):
+    web: bool | None = None
+    image: bool | None = None
+
+
+class EnginesCapabilities(OpenSERPModel):
+    engines: dict[str, EngineCapability] | None = None
+    modes: dict[str, ModeCapability] | None = None

openserp/py.typed

@@ -0,0 +1 @@
+

openserp-0.1.0.dist-info/METADATA

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: openserp
+Version: 0.1.0
+Summary: Python SDK for the OpenSERP self-hosted server and OpenSERP Cloud.
+Project-URL: Homepage, https://openserp.org
+Project-URL: Documentation, https://openserp.org/docs
+Project-URL: Repository, https://github.com/karust/openserp
+Project-URL: Issues, https://github.com/karust/openserp/issues
+Author: OpenSERP
+License-Expression: MIT
+Keywords: ai-grounding,baidu,bing,duckduckgo,ecosia,google,openserp,search,seo,serp,yandex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# OpenSERP Python SDK
+
+Alpha: API may change before 1.0.
+
+Python SDK for the OpenSERP self-hosted server and OpenSERP Cloud. The same client works against both backends.
+
+## Install
+
+```bash
+pip install openserp
+```
+
+For DataFrame export:
+
+```bash
+pip install "openserp[pandas]"
+```
+
+## OSS Mode
+
+OSS mode is the default. Run the open source server locally, then point the SDK at it:
+
+```python
+from openserp import OpenSERP
+
+client = OpenSERP(base_url="http://localhost:7000")
+
+resp = client.search(
+    engine="google",
+    text="openserp",
+    limit=10,
+    region="US",
+)
+
+print(resp.results[0].title, resp.results[0].url)
+```
+
+If you omit every option, the client uses `http://localhost:7000`.
+
+## Cloud Mode
+
+Pass an API key and the client defaults to `https://api.openserp.org/v1`.
+
+```python
+import os
+
+from openserp import OpenSERP
+
+client = OpenSERP(api_key=os.environ["OPENSERP_API_KEY"])
+resp = client.search(engine="google", text="openserp")
+
+print(resp.results[0].title)
+print(client.last_response.credits)
+```
+
+## Async
+
+```python
+import asyncio
+import os
+
+from openserp import AsyncOpenSERP
+
+
+async def main() -> None:
+    async with AsyncOpenSERP(api_key=os.environ["OPENSERP_API_KEY"]) as client:
+        resp = await client.search(engine="google", text="openserp")
+        print(resp.results[0].title)
+
+
+asyncio.run(main())
+```
+
+## Mega Search
+
+```python
+from openserp import OpenSERP
+
+client = OpenSERP()
+
+mega = client.mega_search(
+    text="openserp",
+    engines=["google", "bing", "yandex"],
+    mode="balanced",
+)
+
+df = mega.to_pandas()
+print(df[["rank", "title", "url", "engine"]])
+```
+
+Convenience helpers are also available:
+
+```python
+client.fast_search(text="openserp", engines=["google", "bing"])
+client.any_search(text="openserp", engines=["google", "bing"])
+client.mega_image(text="golang logo", engines=["google", "bing"])
+```
+
+## AI / RAG
+
+```python
+from openserp import OpenSERP
+
+client = OpenSERP()
+resp = client.search(engine="google", text="latest postgres indexing guide", limit=5)
+
+context = "\n\n".join(
+    f"{item.title}\n{item.url}\n{item.snippet}"
+    for item in resp.results
+)
+
+prompt = f"Use these web results as grounding:\n\n{context}\n\nSummarize the key points."
+```
+
+## SEO Keyword Tracker
+
+```python
+from openserp import OpenSERP
+
+client = OpenSERP()
+keywords = ["openserp", "serp api", "google search api"]
+frames = []
+
+for keyword in keywords:
+    resp = client.search(engine="google", text=keyword, region="US", limit=10)
+    frame = resp.to_pandas()
+    frame["keyword"] = keyword
+    frames.append(frame)
+
+report = __import__("pandas").concat(frames, ignore_index=True)
+report.to_csv("rank-report.csv", index=False)
+```
+
+## Async Batch
+
+```python
+import asyncio
+
+from openserp import AsyncOpenSERP
+
+
+async def main() -> None:
+    sem = asyncio.Semaphore(20)
+    queries = [f"keyword {i}" for i in range(500)]
+
+    async with AsyncOpenSERP() as client:
+        async def run(query: str):
+            async with sem:
+                return await client.search(engine="google", text=query, limit=10)
+
+        responses = await asyncio.gather(*(run(query) for query in queries))
+        print(len(responses))
+
+
+asyncio.run(main())
+```
+
+## Endpoint Availability
+
+Search endpoints work in both modes. Operational OSS endpoints such as `health()`, `stats()`, `parse_google()`, and `parse_bing()` require a self-hosted server and raise `OssOnlyError` in Cloud mode.
+
+Cloud account endpoints such as `me()`, `pricing()`, `engines_status()`, and `engines_capabilities()` require Cloud mode and raise `CloudOnlyError` in OSS mode.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev,pandas]"
+pytest
+ruff check .
+mypy src
+python -m build
+```
+
+The project is scaffolded for `uv` too:
+
+```bash
+uv build
+```

openserp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+openserp/__init__.py,sha256=Le2lAfY38d2mLKIseiUILcQNBJbTkrtQEwaYHYtd5u8,1235
+openserp/backend.py,sha256=I2sw_NzhamwJAyHBtMFA_h6v9Qg8WkLIdalojVyK2XU,951
+openserp/client.py,sha256=gFocl1laNI9GuonoqknHLBA4Di7fDYg_revmKGlMXkg,19532
+openserp/errors.py,sha256=38HxqEU1xjicr0oSOY0gWN7bS6C5C6IreNrnP3Dj4bg,2181
+openserp/models.py,sha256=hY6vfNAov3kmJAWBjzi1GzuNrdbTnPZ5w9Rxui13npI,8511
+openserp/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+openserp-0.1.0.dist-info/METADATA,sha256=MCWk57fLJijWuVpeQ_UhHMmgYipwm9D6LHaaroMVcPk,5187
+openserp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+openserp-0.1.0.dist-info/RECORD,,

openserp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any