cloro 0.1.0__py3-none-any.whl

cloro/__init__.py

@@ -0,0 +1,52 @@
+"""cloro — the official Python SDK.
+
+One API for Google Search and every AI answer engine (ChatGPT, Gemini,
+Perplexity, Copilot, Grok, AI Overview, AI Mode). Real-time, structured JSON.
+
+    from cloro import Cloro
+
+    client = Cloro(api_key="sk_live_...")
+    res = client.monitor.chatgpt(prompt="What is cloro?", country="US")
+    print(res["result"]["text"])
+"""
+from ._client import Cloro
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    CloroError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    TaskError,
+    TaskFailedError,
+    TaskTimeoutError,
+)
+from ._version import __version__
+from .resources import AsyncTask
+
+__all__ = [
+    "Cloro",
+    "AsyncTask",
+    "__version__",
+    "CloroError",
+    "APIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "InternalServerError",
+    "TaskError",
+    "TaskFailedError",
+    "TaskTimeoutError",
+]

cloro/_client.py

@@ -0,0 +1,208 @@
+"""HTTP client for the cloro API."""
+from __future__ import annotations
+
+import os
+import platform
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    CloroError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from ._version import __version__
+from .resources.async_tasks import AsyncTasksResource
+from .resources.monitor import MonitorResource
+
+DEFAULT_BASE_URL = "https://api.cloro.dev"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+
+_STATUS_MAP = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+}
+
+# Status codes that are safe to retry with backoff.
+_RETRY_STATUS = {429, 500, 502, 503, 504}
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential backoff: 0.5s, 1s, 2s, ... capped at 8s."""
+    return min(0.5 * (2 ** (attempt - 1)), 8.0)
+
+
+def _parse_retry_after(response: httpx.Response) -> Optional[float]:
+    value = response.headers.get("retry-after")
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def _make_status_error(response: httpx.Response) -> APIStatusError:
+    try:
+        body: Any = response.json()
+    except Exception:
+        body = None
+
+    message: Optional[str] = None
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            message = err.get("message")
+        elif isinstance(err, str):
+            message = err
+    message = message or (response.text or f"HTTP {response.status_code}")
+
+    cls = _STATUS_MAP.get(response.status_code)
+    if cls is None:
+        cls = InternalServerError if response.status_code >= 500 else APIStatusError
+    return cls(
+        message,
+        status_code=response.status_code,
+        response=response,
+        body=body,
+    )
+
+
+class Cloro:
+    """Client for the cloro API.
+
+    One API for Google Search and every AI answer engine (ChatGPT, Gemini,
+    Perplexity, Copilot, Grok, AI Overview, AI Mode). Real-time, structured JSON.
+
+    Args:
+        api_key: Your cloro API key (``sk_live_...``). Falls back to the
+            ``CLORO_API_KEY`` environment variable.
+        base_url: Override the API base URL (default ``https://api.cloro.dev``).
+        timeout: Per-request timeout in seconds.
+        max_retries: Retries for timeouts, connection errors, and 429/5xx.
+        http_client: Inject a preconfigured ``httpx.Client`` (proxies, custom
+            transport, testing). If provided, ``timeout`` is ignored.
+
+    Example:
+        >>> from cloro import Cloro
+        >>> client = Cloro(api_key="sk_live_...")
+        >>> res = client.monitor.chatgpt(
+        ...     prompt="What do you know about Acme Corp?",
+        ...     country="US",
+        ...     include={"markdown": True},
+        ... )
+        >>> res["result"]["text"]
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("CLORO_API_KEY")
+        if not api_key:
+            raise CloroError(
+                "No API key provided. Pass api_key=... or set the "
+                "CLORO_API_KEY environment variable."
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+        self.monitor = MonitorResource(self)
+        self.async_tasks = AsyncTasksResource(self)
+
+    # -- reference data -------------------------------------------------
+
+    def countries(self, model: Optional[str] = None) -> Any:
+        """List supported countries, optionally filtered by engine ``model``."""
+        params = {"model": model} if model else None
+        return self.request("GET", "/v1/countries", params=params)
+
+    def states(self) -> Any:
+        """List supported US states (for location-targeted Google requests)."""
+        return self.request("GET", "/v1/states")
+
+    # -- transport ------------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"cloro-python/{__version__} (python {platform.python_version()})",
+        }
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(
+                    method, url, json=json, params=params, headers=self._headers()
+                )
+            except httpx.TimeoutException as exc:
+                if attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise APITimeoutError(f"Request to {url} timed out") from exc
+            except httpx.HTTPError as exc:
+                if attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise APIConnectionError(str(exc)) from exc
+
+            if response.status_code >= 400:
+                if response.status_code in _RETRY_STATUS and attempt < self.max_retries:
+                    attempt += 1
+                    retry_after = _parse_retry_after(response)
+                    time.sleep(retry_after if retry_after is not None else _backoff(attempt))
+                    continue
+                raise _make_status_error(response)
+
+            if not response.content:
+                return None
+            return response.json()
+
+    # -- lifecycle ------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (only if the SDK created it)."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "Cloro":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()

cloro/_exceptions.py

@@ -0,0 +1,117 @@
+"""Exception hierarchy for the cloro SDK.
+
+All errors derive from :class:`CloroError`, so a single ``except CloroError``
+catches everything the SDK can raise. HTTP failures map to
+:class:`APIStatusError` subclasses by status code; the async task poller raises
+:class:`TaskFailedError` / :class:`TaskTimeoutError`.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+__all__ = [
+    "CloroError",
+    "APIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "InternalServerError",
+    "TaskError",
+    "TaskFailedError",
+    "TaskTimeoutError",
+]
+
+
+class CloroError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class APIError(CloroError):
+    """Base class for errors originating from an HTTP request."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        response: Any = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+        self.body = body
+
+
+class APIConnectionError(APIError):
+    """The request could not reach the cloro API (DNS, TLS, socket errors)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out before a response was received."""
+
+
+class APIStatusError(APIError):
+    """The API returned a non-2xx status code."""
+
+
+class BadRequestError(APIStatusError):
+    """400 — the request was malformed or failed validation."""
+
+
+class AuthenticationError(APIStatusError):
+    """401 — the API key is missing or invalid."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """403 — the API key is not allowed to perform this action."""
+
+
+class NotFoundError(APIStatusError):
+    """404 — the requested resource does not exist."""
+
+
+class ConflictError(APIStatusError):
+    """409 — the request conflicts with current state (e.g. concurrency limit)."""
+
+
+class RateLimitError(APIStatusError):
+    """429 — too many requests; retry after backing off."""
+
+
+class InternalServerError(APIStatusError):
+    """5xx — the API failed to process the request."""
+
+
+class TaskError(CloroError):
+    """Base class for async task queue errors."""
+
+
+class TaskFailedError(TaskError):
+    """An async task reached the ``FAILED`` terminal status while polling."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        task: Any = None,
+        response: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.task = task
+        self.response = response
+
+
+class TaskTimeoutError(TaskError):
+    """An async task did not reach a terminal status within the poll timeout."""
+
+    def __init__(self, message: str, *, task: Any = None) -> None:
+        super().__init__(message)
+        self.task = task

cloro/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cloro/resources/__init__.py

@@ -0,0 +1,4 @@
+from .async_tasks import AsyncTask, AsyncTasksResource
+from .monitor import MonitorResource
+
+__all__ = ["MonitorResource", "AsyncTasksResource", "AsyncTask"]

cloro/resources/async_tasks.py

@@ -0,0 +1,215 @@
+"""Async task queue — enqueue work, then poll to completion.
+
+This is where the SDK earns its keep over raw HTTP: :meth:`AsyncTasksResource.wait`
+polls ``GET /v1/async/task/{id}`` with interval backoff and a timeout, and
+:meth:`AsyncTasksResource.run` collapses create-then-wait into a single call.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+
+from .._exceptions import TaskFailedError, TaskTimeoutError
+
+if TYPE_CHECKING:
+    from .._client import Cloro
+
+TERMINAL_STATUSES = frozenset({"COMPLETED", "FAILED"})
+
+# Provider identifiers accepted by the ``taskType`` field.
+TaskType = str
+
+TaskRef = Union["AsyncTask", str]
+
+
+@dataclass
+class AsyncTask:
+    """A handle to a queued task. Returned by :meth:`AsyncTasksResource.create`."""
+
+    id: str
+    status: str = "QUEUED"
+    task_type: Optional[str] = None
+    priority: Optional[int] = None
+    created_at: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def _from_summary(cls, summary: Dict[str, Any]) -> "AsyncTask":
+        return cls(
+            id=summary["id"],
+            status=summary.get("status", "QUEUED"),
+            task_type=summary.get("taskType"),
+            priority=summary.get("priority"),
+            created_at=summary.get("createdAt"),
+            raw=summary,
+        )
+
+
+def _task_id(task: TaskRef) -> str:
+    return task.id if isinstance(task, AsyncTask) else task
+
+
+def _to_request(task: Dict[str, Any]) -> Dict[str, Any]:
+    """Normalize a task dict (snake_case or camelCase) into the API's shape."""
+    out: Dict[str, Any] = {
+        "taskType": task.get("task_type", task.get("taskType")),
+        "payload": task.get("payload"),
+    }
+    for snake, camel in (
+        ("priority", "priority"),
+        ("idempotency_key", "idempotencyKey"),
+        ("webhook", "webhook"),
+    ):
+        value = task.get(snake, task.get(camel))
+        if value is not None:
+            out[camel] = value
+    return out
+
+
+class AsyncTasksResource:
+    """The ``/v1/async/*`` task queue."""
+
+    def __init__(self, client: "Cloro") -> None:
+        self._client = client
+
+    # -- create ---------------------------------------------------------
+
+    def create(
+        self,
+        task_type: TaskType,
+        payload: Dict[str, Any],
+        *,
+        priority: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+        webhook: Optional[Dict[str, Any]] = None,
+    ) -> AsyncTask:
+        """Enqueue a single task. ``POST /v1/async/task``.
+
+        Args:
+            task_type: One of ``CHATGPT``, ``GEMINI``, ``PERPLEXITY``, ``COPILOT``,
+                ``GROK``, ``AIMODE``, ``GOOGLE``, ``GOOGLE_NEWS``.
+            payload: Provider-specific body (e.g. ``{"prompt": ..., "country": ...}``,
+                or ``{"query": ..., "country": ...}`` for Google Search).
+            priority: 1-10, higher runs first (default 1).
+            idempotency_key: Unique string to dedupe task creation.
+            webhook: ``{"url": ...}`` to be notified on completion.
+        """
+        body = _to_request(
+            {
+                "task_type": task_type,
+                "payload": payload,
+                "priority": priority,
+                "idempotency_key": idempotency_key,
+                "webhook": webhook,
+            }
+        )
+        resp = self._client.request("POST", "/v1/async/task", json=body)
+        return AsyncTask._from_summary(resp["task"])
+
+    def create_batch(self, tasks: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Enqueue up to 500 tasks in one call. ``POST /v1/async/task/batch``.
+
+        Each item is a dict with ``task_type`` and ``payload`` (plus optional
+        ``priority`` / ``idempotency_key`` / ``webhook``). Returns the per-task
+        ``results`` array, preserving input order. Successful items carry a
+        ``task`` field; failed items carry an ``error`` field.
+        """
+        body = [_to_request(t) for t in tasks]
+        resp = self._client.request("POST", "/v1/async/task/batch", json=body)
+        return resp.get("results", [])
+
+    # -- read -----------------------------------------------------------
+
+    def retrieve(self, task: TaskRef) -> Dict[str, Any]:
+        """Fetch a task's current status. ``GET /v1/async/task/{id}``.
+
+        The ``response`` field is present only once the task is ``COMPLETED``
+        or ``FAILED``.
+        """
+        return self._client.request("GET", f"/v1/async/task/{_task_id(task)}")
+
+    def status(self) -> Dict[str, Any]:
+        """Queue-wide status for your organization. ``GET /v1/async/status``."""
+        return self._client.request("GET", "/v1/async/status")
+
+    # -- poll -----------------------------------------------------------
+
+    def wait(
+        self,
+        task: TaskRef,
+        *,
+        poll_interval: float = 2.0,
+        timeout: float = 300.0,
+        backoff: float = 1.5,
+        max_interval: float = 15.0,
+    ) -> Dict[str, Any]:
+        """Poll a task until it reaches a terminal status, then return it.
+
+        Args:
+            task: An :class:`AsyncTask` or a task id string.
+            poll_interval: Seconds before the first poll; grows by ``backoff``.
+            timeout: Give up after this many seconds (raises
+                :class:`TaskTimeoutError`).
+            backoff: Multiplier applied to the interval after each poll.
+            max_interval: Ceiling for the polling interval.
+
+        Returns:
+            The full ``TaskStatusResponse`` dict, including ``response`` once
+            ``COMPLETED``.
+
+        Raises:
+            TaskFailedError: the task reached ``FAILED``.
+            TaskTimeoutError: the task did not finish within ``timeout``.
+        """
+        deadline = time.monotonic() + timeout
+        interval = poll_interval
+        while True:
+            status = self.retrieve(task)
+            state = status.get("task", {}).get("status")
+            if state == "COMPLETED":
+                return status
+            if state == "FAILED":
+                raise TaskFailedError(
+                    f"Task {_task_id(task)} failed", task=task, response=status
+                )
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TaskTimeoutError(
+                    f"Task {_task_id(task)} did not complete within {timeout}s "
+                    f"(last status: {state})",
+                    task=task,
+                )
+            time.sleep(min(interval, remaining))
+            interval = min(interval * backoff, max_interval)
+
+    def run(
+        self,
+        task_type: TaskType,
+        payload: Dict[str, Any],
+        *,
+        priority: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+        webhook: Optional[Dict[str, Any]] = None,
+        poll_interval: float = 2.0,
+        timeout: float = 300.0,
+        backoff: float = 1.5,
+        max_interval: float = 15.0,
+    ) -> Dict[str, Any]:
+        """Create a task and block until it completes. Convenience for
+        :meth:`create` + :meth:`wait`."""
+        task = self.create(
+            task_type,
+            payload,
+            priority=priority,
+            idempotency_key=idempotency_key,
+            webhook=webhook,
+        )
+        return self.wait(
+            task,
+            poll_interval=poll_interval,
+            timeout=timeout,
+            backoff=backoff,
+            max_interval=max_interval,
+        )

cloro/resources/monitor.py

@@ -0,0 +1,117 @@
+"""Synchronous monitor endpoints — one call per AI engine or Google Search."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+if TYPE_CHECKING:
+    from .._client import Cloro
+
+
+class MonitorResource:
+    """Real-time ``POST /v1/monitor/*`` endpoints.
+
+    Each method blocks until the engine responds and returns the parsed
+    ``{"success": ..., "result": {...}}`` envelope. For high-volume or
+    long-running work, prefer the async task queue (:attr:`Cloro.async_tasks`).
+    """
+
+    def __init__(self, client: "Cloro") -> None:
+        self._client = client
+
+    def _run(self, path: str, body: Dict[str, Any]) -> Any:
+        payload = {k: v for k, v in body.items() if v is not None}
+        return self._client.request("POST", path, json=payload)
+
+    # -- AI answer engines (prompt-based) -------------------------------
+
+    def chatgpt(
+        self, prompt: str, country: str, *, include: Optional[Dict[str, bool]] = None, **extra: Any
+    ) -> Any:
+        """Monitor ChatGPT. ``POST /v1/monitor/chatgpt``."""
+        return self._run(
+            "/v1/monitor/chatgpt",
+            {"prompt": prompt, "country": country, "include": include, **extra},
+        )
+
+    def gemini(
+        self, prompt: str, country: str, *, include: Optional[Dict[str, bool]] = None, **extra: Any
+    ) -> Any:
+        """Monitor Google Gemini. ``POST /v1/monitor/gemini``."""
+        return self._run(
+            "/v1/monitor/gemini",
+            {"prompt": prompt, "country": country, "include": include, **extra},
+        )
+
+    def perplexity(
+        self, prompt: str, country: str, *, include: Optional[Dict[str, bool]] = None, **extra: Any
+    ) -> Any:
+        """Monitor Perplexity. ``POST /v1/monitor/perplexity``."""
+        return self._run(
+            "/v1/monitor/perplexity",
+            {"prompt": prompt, "country": country, "include": include, **extra},
+        )
+
+    def copilot(
+        self, prompt: str, country: str, *, include: Optional[Dict[str, bool]] = None, **extra: Any
+    ) -> Any:
+        """Monitor Microsoft Copilot. ``POST /v1/monitor/copilot``."""
+        return self._run(
+            "/v1/monitor/copilot",
+            {"prompt": prompt, "country": country, "include": include, **extra},
+        )
+
+    def grok(
+        self, prompt: str, country: str, *, include: Optional[Dict[str, bool]] = None, **extra: Any
+    ) -> Any:
+        """Monitor Grok. ``POST /v1/monitor/grok``."""
+        return self._run(
+            "/v1/monitor/grok",
+            {"prompt": prompt, "country": country, "include": include, **extra},
+        )
+
+    def aimode(
+        self, prompt: str, country: str, *, include: Optional[Dict[str, bool]] = None, **extra: Any
+    ) -> Any:
+        """Monitor Google AI Mode. ``POST /v1/monitor/aimode``."""
+        return self._run(
+            "/v1/monitor/aimode",
+            {"prompt": prompt, "country": country, "include": include, **extra},
+        )
+
+    # -- Google Search (query-based) ------------------------------------
+
+    def google(
+        self,
+        query: str,
+        country: str,
+        *,
+        location: Optional[str] = None,
+        uule: Optional[str] = None,
+        device: Optional[str] = None,
+        pages: Optional[int] = None,
+        include: Optional[Dict[str, bool]] = None,
+        **extra: Any,
+    ) -> Any:
+        """Monitor Google Search (SERP). ``POST /v1/monitor/google``."""
+        return self._run(
+            "/v1/monitor/google",
+            {
+                "query": query,
+                "country": country,
+                "location": location,
+                "uule": uule,
+                "device": device,
+                "pages": pages,
+                "include": include,
+                **extra,
+            },
+        )
+
+    def google_news(
+        self, query: str, country: str, *, include: Optional[Dict[str, bool]] = None, **extra: Any
+    ) -> Any:
+        """Monitor Google News. ``POST /v1/monitor/google/news``."""
+        return self._run(
+            "/v1/monitor/google/news",
+            {"query": query, "country": country, "include": include, **extra},
+        )

cloro-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: cloro
+Version: 0.1.0
+Summary: Official Python SDK for the cloro API — one API for Google Search and every AI answer engine (ChatGPT, Gemini, Perplexity, Copilot, Grok, AI Overview, AI Mode).
+Project-URL: Homepage, https://cloro.dev
+Project-URL: Documentation, https://cloro.dev/docs
+Project-URL: Source, https://github.com/cloro-dev/cloro-python
+Project-URL: Issues, https://github.com/cloro-dev/cloro-python/issues
+Author-email: cloro <support@cloro.dev>
+License: MIT
+License-File: LICENSE
+Keywords: ai search,ai visibility,chatgpt,cloro,copilot,gemini,geo,google search,perplexity,seo,serp,serp api,web scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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.8
+Requires-Dist: httpx<1,>=0.23
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cloro Python SDK
+
+The official Python client for [**cloro**](https://cloro.dev) — one API for
+Google Search and every AI answer engine (ChatGPT, Gemini, Perplexity, Copilot,
+Grok, AI Overview, AI Mode). Real-time, structured JSON.
+
+Use the SDK, or [just `curl` it](https://cloro.dev/docs) — same clean response
+either way. The SDK adds typed methods, sensible retries, and a polling helper
+for the async task queue so you don't hand-roll it.
+
+## Installation
+
+```bash
+pip install cloro
+```
+
+Requires Python 3.8+.
+
+## Quickstart
+
+```python
+from cloro import Cloro
+
+client = Cloro(api_key="sk_live_...")  # or set CLORO_API_KEY
+
+res = client.monitor.chatgpt(
+    prompt="What do you know about Acme Corp?",
+    country="US",
+    include={"markdown": True},
+)
+
+print(res["result"]["text"])
+for source in res["result"]["sources"]:
+    print(source["position"], source["url"], source["label"])
+```
+
+The API key is read from the `CLORO_API_KEY` environment variable when you don't
+pass `api_key=`. Get a key (and 500 free credits) at
+[dashboard.cloro.dev](https://dashboard.cloro.dev/).
+
+## Engines
+
+Every engine is a method on `client.monitor`. AI engines take a `prompt`;
+Google Search and Google News take a `query`.
+
+```python
+client.monitor.chatgpt(prompt="...", country="US")
+client.monitor.gemini(prompt="...", country="US")
+client.monitor.perplexity(prompt="...", country="US")
+client.monitor.copilot(prompt="...", country="US")
+client.monitor.grok(prompt="...", country="US")
+client.monitor.aimode(prompt="...", country="US")           # Google AI Mode
+
+client.monitor.google(query="best crm", country="US", pages=1)
+client.monitor.google_news(query="acme corp", country="US")
+```
+
+Pass `include={...}` to request extra formats — `markdown`, `html`,
+`searchQueries`, `shopping`, and more, depending on the engine.
+
+## Async task queue
+
+For high-volume or long-running work, enqueue tasks and poll them to completion.
+`run()` does create-then-wait in one call:
+
+```python
+result = client.async_tasks.run(
+    task_type="CHATGPT",
+    payload={"prompt": "What is cloro?", "country": "US"},
+)
+print(result["response"])       # present once COMPLETED
+print(result["credits"])        # credits reserved / charged
+```
+
+Prefer to manage the lifecycle yourself:
+
+```python
+task = client.async_tasks.create(
+    task_type="GOOGLE",
+    payload={"query": "serp api", "country": "US"},
+    priority=5,
+)
+status = client.async_tasks.retrieve(task)   # non-blocking snapshot
+result = client.async_tasks.wait(task, timeout=120, poll_interval=2)
+```
+
+Batch up to 500 tasks in a single request (results preserve input order):
+
+```python
+results = client.async_tasks.create_batch([
+    {"task_type": "CHATGPT", "payload": {"prompt": "q1", "country": "US"}},
+    {"task_type": "PERPLEXITY", "payload": {"prompt": "q2", "country": "GB"}},
+])
+for item in results:
+    if item["success"]:
+        client.async_tasks.wait(item["task"]["id"])
+    else:
+        print("failed:", item["error"]["message"])
+```
+
+Queue-wide status:
+
+```python
+client.async_tasks.status()   # queued / processing counts, concurrency usage
+```
+
+Valid `task_type` values: `CHATGPT`, `GEMINI`, `PERPLEXITY`, `COPILOT`, `GROK`,
+`AIMODE`, `GOOGLE`, `GOOGLE_NEWS`.
+
+## Configuration
+
+```python
+client = Cloro(
+    api_key="sk_live_...",
+    base_url="https://api.cloro.dev",  # override if needed
+    timeout=60.0,                       # per-request seconds
+    max_retries=2,                      # timeouts, connection errors, 429/5xx
+)
+```
+
+The client is a context manager and pools connections:
+
+```python
+with Cloro() as client:
+    client.monitor.chatgpt(prompt="...", country="US")
+```
+
+## Error handling
+
+All errors subclass `CloroError`. HTTP failures map to status-specific types:
+
+```python
+from cloro import Cloro, AuthenticationError, RateLimitError, CloroError
+
+try:
+    client.monitor.chatgpt(prompt="...", country="US")
+except AuthenticationError:
+    ...  # 401 — bad or missing API key
+except RateLimitError as e:
+    ...  # 429 — back off and retry
+except CloroError as e:
+    ...  # everything else
+```
+
+`BadRequestError` (400), `PermissionDeniedError` (403), `NotFoundError` (404),
+`ConflictError` (409), and `InternalServerError` (5xx) are also available, along
+with `TaskFailedError` / `TaskTimeoutError` from the poller and
+`APITimeoutError` / `APIConnectionError` from the transport.
+
+## Reference data
+
+```python
+client.countries()             # supported countries
+client.countries(model="chatgpt")
+client.states()                # US states for location-targeted Google
+```
+
+## Links
+
+- Docs: <https://cloro.dev/docs>
+- API reference (OpenAPI): <https://cloro.dev/docs/api-reference/openapi.json>
+- Dashboard: <https://dashboard.cloro.dev/>
+- TypeScript SDK: [cloro-node](https://github.com/cloro-dev/cloro-node)
+
+## License
+
+MIT

cloro-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+cloro/__init__.py,sha256=CNVRYtwYprHiVJ9eC-nPB4uKGKarVISV5BP3hIy5eKE,1204
+cloro/_client.py,sha256=9lYAFL17yjrk1ntZB-KhyYVwsjaHDGWDWYo8_NUQetM,6676
+cloro/_exceptions.py,sha256=h2ATxunpGCKK7Jany9RYjfKYmogeWgiPvOjP1419V8Y,3017
+cloro/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+cloro/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cloro/resources/__init__.py,sha256=xc--FAgJpPJ8tZfnbGSTNLzdP_ptcxB1SfMj-SW4270,158
+cloro/resources/async_tasks.py,sha256=KXem2ZCNpmWoKHqkq22DaMXuL3Zj4SXt1UsJGXqEA14,7543
+cloro/resources/monitor.py,sha256=Kjgjs7dDFe0AAfDVyF6x0BzIytZPieJVSKgs6-7SOfI,4154
+cloro-0.1.0.dist-info/METADATA,sha256=Hxl7A01mU65HS2iZ9pdRJdeVfookDGcm3Ga2pfkyrWc,6181
+cloro-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+cloro-0.1.0.dist-info/licenses/LICENSE,sha256=4sdWt3wrB2gINd2nu57FAMdVqjr_bnpwB3aK4NJ5LxE,1062
+cloro-0.1.0.dist-info/RECORD,,

cloro-0.1.0.dist-info/WHEEL

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

cloro-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cloro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.