clous 0.1.0__py3-none-any.whl

clous/__init__.py

@@ -0,0 +1,56 @@
+"""Clous — the official Python SDK for the Clous SEC/EDGAR API.
+
+Quickstart::
+
+    from clous import Clous
+
+    client = Clous()  # reads CLOUS_API_KEY from the environment
+
+    # Search filings
+    page = client.filings.search(form_type="8-K", limit=10)
+    for filing in page:
+        print(filing["accession"])
+
+    # Structured XBRL financials for one company
+    facts = client.financials.get("0000320193", concept="Revenues")
+
+    # Grounded Q&A
+    ans = client.answer("What did Apple report as revenue last quarter?", ticker="AAPL")
+
+    # Auto-paginate every record
+    for ev in client.events.iterate(ticker="NVDA", importance="high", max_items=500):
+        print(ev["event_type"])
+"""
+
+from ._models import Page, PageInfo
+from ._version import __version__
+from .client import Clous
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ClousConnectionError,
+    ClousError,
+    ClousTimeoutError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = [
+    "Clous",
+    "Page",
+    "PageInfo",
+    "ClousError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "ServerError",
+    "ClousConnectionError",
+    "ClousTimeoutError",
+    "__version__",
+]

clous/_client.py

@@ -0,0 +1,240 @@
+"""The low-level HTTP transport for the Clous SDK."""
+
+from __future__ import annotations
+
+import json as _json
+import os
+import random
+import time
+from typing import Any, Dict, Iterator, Mapping, Optional, Union
+
+import httpx
+
+from ._models import Page
+from ._version import __version__
+from .exceptions import (
+    APIError,
+    ClousConnectionError,
+    ClousError,
+    ClousTimeoutError,
+    RateLimitError,
+    ServerError,
+    error_from_status,
+)
+
+DEFAULT_BASE_URL = "https://api.clous.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+# Status codes we retry (in addition to network errors).
+_RETRY_STATUS = {429, 500, 502, 503, 504}
+
+ParamValue = Union[str, int, float, bool, None]
+
+
+def _coerce_params(params: Optional[Mapping[str, Any]]) -> Dict[str, str]:
+    """Drop ``None``/empty values and stringify the rest (booleans -> true/false).
+
+    ``output_schema`` is JSON-encoded if a dict/list is passed.
+    """
+    out: Dict[str, str] = {}
+    if not params:
+        return out
+    for key, value in params.items():
+        if value is None or value == "":
+            continue
+        if key == "output_schema" and isinstance(value, (dict, list)):
+            out[key] = _json.dumps(value, separators=(",", ":"))
+        elif isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        elif isinstance(value, (list, tuple)):
+            out[key] = ",".join(str(v) for v in value)
+        else:
+            out[key] = str(value)
+    return out
+
+
+class HTTPClient:
+    """Thin wrapper over :class:`httpx.Client` that speaks the Clous envelope."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.Client] = None,
+        default_headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("CLOUS_API_KEY")
+        base_url = base_url or os.environ.get("CLOUS_BASE_URL") or DEFAULT_BASE_URL
+        # The OpenAI-compatible base may be passed with a trailing /v1; strip it
+        # so resource paths (which include /v1) resolve correctly.
+        base_url = base_url.rstrip("/")
+        if base_url.endswith("/v1"):
+            base_url = base_url[: -len("/v1")]
+
+        self.api_key = api_key
+        self.base_url = base_url
+        self.max_retries = max_retries
+
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"clous-python/{__version__}",
+        }
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        if default_headers:
+            headers.update(default_headers)
+
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout, follow_redirects=True)
+        self._headers = headers
+
+    # ------------------------------------------------------------------ core
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        raw: bool = False,
+    ) -> Any:
+        """Issue a request and return a :class:`Page` (or raw dict if ``raw``)."""
+        url = self.base_url + path
+        query = _coerce_params(params)
+        headers = dict(self._headers)
+        content = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            content = _json.dumps(body)
+
+        response = self._send_with_retries(method, url, params=query, headers=headers, content=content)
+        return self._parse(response, raw=raw)
+
+    def _send_with_retries(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Dict[str, str],
+        headers: Dict[str, str],
+        content: Optional[str],
+    ) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(
+                    method, url, params=params, headers=headers, content=content
+                )
+            except httpx.TimeoutException as exc:
+                if attempt >= self.max_retries:
+                    raise ClousTimeoutError(f"Request to {url} timed out: {exc}") from exc
+            except httpx.HTTPError as exc:
+                if attempt >= self.max_retries:
+                    raise ClousConnectionError(f"Network error calling {url}: {exc}") from exc
+            else:
+                if response.status_code not in _RETRY_STATUS or attempt >= self.max_retries:
+                    return response
+
+            # Honor Retry-After when present (only available if we got a response).
+            sleep_for = self._backoff(attempt)
+            try:
+                retry_after = response.headers.get("retry-after")  # type: ignore[name-defined]
+                if retry_after:
+                    sleep_for = max(sleep_for, float(retry_after))
+            except (NameError, ValueError):
+                pass
+            time.sleep(sleep_for)
+            attempt += 1
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        # Exponential backoff with jitter: 0.5, 1, 2, ... capped at 8s.
+        base = min(0.5 * (2 ** attempt), 8.0)
+        return base + random.uniform(0, 0.25)
+
+    def _parse(self, response: httpx.Response, *, raw: bool) -> Any:
+        request_id = response.headers.get("x-request-id")
+        if not response.is_success:
+            message, parsed = self._extract_error(response)
+            raise error_from_status(
+                response.status_code,
+                message,
+                request_id=request_id,
+                body=parsed,
+                response=response,
+            )
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise APIError(
+                f"Could not decode JSON response: {exc}",
+                status_code=response.status_code,
+                request_id=request_id,
+                body=response.text,
+                response=response,
+            ) from exc
+
+        if raw:
+            return payload
+        return Page(payload, headers=dict(response.headers))
+
+    @staticmethod
+    def _extract_error(response: httpx.Response) -> Any:
+        parsed: Any = None
+        message = f"Clous API request failed with status {response.status_code}"
+        try:
+            parsed = response.json()
+            if isinstance(parsed, dict):
+                detail = parsed.get("error") or parsed.get("detail") or parsed.get("message")
+                if isinstance(detail, dict):
+                    detail = detail.get("message") or detail.get("detail")
+                if detail:
+                    message = str(detail)
+                elif parsed.get("warnings"):
+                    message = "; ".join(str(w) for w in parsed["warnings"])
+        except ValueError:
+            text = response.text.strip()
+            if text:
+                message = text[:2000]
+                parsed = text
+        return message, parsed
+
+    # ------------------------------------------------------------ pagination
+    def paginate(
+        self,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        max_items: Optional[int] = None,
+    ) -> Iterator[Any]:
+        """Yield every record across all pages, following ``page.next_cursor``."""
+        params = dict(params or {})
+        yielded = 0
+        cursor: Optional[str] = params.get("cursor")
+        while True:
+            if cursor is not None:
+                params["cursor"] = cursor
+            page = self.request("GET", path, params=params)
+            for record in page:
+                yield record
+                yielded += 1
+                if max_items is not None and yielded >= max_items:
+                    return
+            if not page.has_more or not page.next_cursor:
+                return
+            cursor = page.next_cursor
+
+    # --------------------------------------------------------------- cleanup
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "HTTPClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

clous/_models.py

@@ -0,0 +1,121 @@
+"""Lightweight response models for the Clous envelope.
+
+Every Clous endpoint returns a JSON envelope::
+
+    {
+        "data": [...] | {...},
+        "page": {"limit": int, "next_cursor": str | None, "has_more": bool},
+        "as_of": "...",
+        "source": "...",
+        "query_echo": {...},
+        "warnings": [...]
+    }
+
+:class:`Page` wraps that envelope. It behaves like the ``data`` list for the
+common case (iteration, indexing, ``len``) while still exposing the pagination
+metadata and response headers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterator, List, Optional
+
+
+@dataclass
+class PageInfo:
+    """The ``page`` block of the envelope."""
+
+    limit: Optional[int] = None
+    next_cursor: Optional[str] = None
+    has_more: bool = False
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Optional[Dict[str, Any]]) -> "PageInfo":
+        d = d or {}
+        return cls(
+            limit=d.get("limit"),
+            next_cursor=d.get("next_cursor"),
+            has_more=bool(d.get("has_more", False)),
+            raw=d,
+        )
+
+
+class Page:
+    """A single page of results plus envelope metadata.
+
+    Iterating, indexing and ``len()`` operate over the ``data`` payload, so for
+    list endpoints you can treat a :class:`Page` like a list of records::
+
+        page = client.filings.search(form_type="8-K")
+        for filing in page:
+            print(filing["accession"])
+        first = page[0]
+
+    The envelope metadata stays available via attributes: ``page.page_info``,
+    ``page.as_of``, ``page.source``, ``page.warnings``, ``page.query_echo``,
+    and the response headers via ``page.request_id`` / ``page.credits_cost`` /
+    ``page.credits_remaining``.
+    """
+
+    def __init__(self, envelope: Dict[str, Any], headers: Optional[Dict[str, str]] = None) -> None:
+        self._envelope = envelope or {}
+        self._headers = headers or {}
+        self.data: Any = self._envelope.get("data")
+        self.page_info: PageInfo = PageInfo.from_dict(self._envelope.get("page"))
+        self.as_of: Optional[str] = self._envelope.get("as_of")
+        self.source: Optional[str] = self._envelope.get("source")
+        self.query_echo: Any = self._envelope.get("query_echo")
+        self.warnings: List[Any] = self._envelope.get("warnings") or []
+
+    # --- envelope helpers --------------------------------------------------
+    @property
+    def next_cursor(self) -> Optional[str]:
+        return self.page_info.next_cursor
+
+    @property
+    def has_more(self) -> bool:
+        return self.page_info.has_more
+
+    @property
+    def raw(self) -> Dict[str, Any]:
+        """The full, unmodified envelope dict."""
+        return self._envelope
+
+    # --- response headers --------------------------------------------------
+    @property
+    def request_id(self) -> Optional[str]:
+        return self._headers.get("x-request-id")
+
+    @property
+    def credits_cost(self) -> Optional[str]:
+        return self._headers.get("x-credits-cost")
+
+    @property
+    def credits_remaining(self) -> Optional[str]:
+        return self._headers.get("x-credits-remaining")
+
+    # --- list-like access over data ---------------------------------------
+    def _as_list(self) -> List[Any]:
+        if isinstance(self.data, list):
+            return self.data
+        if self.data is None:
+            return []
+        return [self.data]
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._as_list())
+
+    def __len__(self) -> int:
+        return len(self._as_list())
+
+    def __getitem__(self, index: int) -> Any:
+        return self._as_list()[index]
+
+    def __bool__(self) -> bool:
+        return bool(self._as_list())
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        n = len(self._as_list())
+        return f"<Page data={n} has_more={self.has_more} next_cursor={self.next_cursor!r}>"

clous/_version.py

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

clous/client.py

@@ -0,0 +1,204 @@
+"""The top-level :class:`Clous` client."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from ._client import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, HTTPClient
+from ._models import Page
+from .resources import (
+    AdvisersResource,
+    BoardResource,
+    BrokerDealersResource,
+    CompensationResource,
+    CyberIncidentsResource,
+    EntitiesResource,
+    EnforcementResource,
+    EventsResource,
+    FilingsResource,
+    FinancialStatementsResource,
+    FinancialsResource,
+    FormCRSResource,
+    FullTextResource,
+    FundsResource,
+    HoldingsResource,
+    IAPDIndividualsResource,
+    InsiderResource,
+    LitigationResource,
+    ManagersResource,
+    MonitorsResource,
+    NTLateResource,
+    OwnershipResource,
+    PatentsResource,
+    PrivateFundStatsResource,
+    PrivateFundsResource,
+    ProxyResource,
+    RaisesResource,
+    TradingSuspensionsResource,
+    WebhooksResource,
+    WhistleblowerResource,
+)
+
+
+class Clous:
+    """Client for the Clous SEC/EDGAR API.
+
+    Args:
+        api_key: Your Clous API key. Falls back to the ``CLOUS_API_KEY`` env var.
+        base_url: API base URL. Defaults to ``https://api.clous.ai`` (or the
+            ``CLOUS_BASE_URL`` env var). The OpenAI-compatible base
+            ``https://api.clous.ai/v1`` is also accepted — a trailing ``/v1`` is
+            normalized away so resource paths resolve correctly.
+        timeout: Per-request timeout in seconds (default 30).
+        max_retries: Retries on 429/5xx and transient network errors (default 3).
+        http_client: An existing ``httpx.Client`` to reuse (optional).
+        default_headers: Extra headers to send on every request.
+
+    Example::
+
+        from clous import Clous
+
+        client = Clous()  # reads CLOUS_API_KEY
+        page = client.filings.search(form_type="8-K", limit=10)
+        for filing in page:
+            print(filing["accession"])
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.Client] = None,
+        default_headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        self._http = HTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+            default_headers=default_headers,
+        )
+
+        # Filings & search
+        self.filings = FilingsResource(self._http)
+        self.full_text = FullTextResource(self._http)
+        self.entities = EntitiesResource(self._http)
+
+        # Ownership / institutional
+        self.insider = InsiderResource(self._http)
+        self.ownership = OwnershipResource(self._http)
+        self.holdings = HoldingsResource(self._http)
+        self.managers = ManagersResource(self._http)
+        self.funds = FundsResource(self._http)
+
+        # Advisers / private funds / brokers
+        self.advisers = AdvisersResource(self._http)
+        self.private_funds = PrivateFundsResource(self._http)
+        self.private_fund_stats = PrivateFundStatsResource(self._http)
+        self.broker_dealers = BrokerDealersResource(self._http)
+        self.form_crs = FormCRSResource(self._http)
+        self.iapd_individuals = IAPDIndividualsResource(self._http)
+
+        # Capital / financials
+        self.raises = RaisesResource(self._http)
+        self.financials = FinancialsResource(self._http)
+        self.financial_statements = FinancialStatementsResource(self._http)
+
+        # Governance & people
+        self.board = BoardResource(self._http)
+        self.compensation = CompensationResource(self._http)
+        self.proxy = ProxyResource(self._http)
+
+        # Enforcement / status / misc datasets
+        self.enforcement = EnforcementResource(self._http)
+        self.litigation = LitigationResource(self._http)
+        self.nt_late = NTLateResource(self._http)
+        self.trading_suspensions = TradingSuspensionsResource(self._http)
+        self.whistleblower = WhistleblowerResource(self._http)
+        self.cyber_incidents = CyberIncidentsResource(self._http)
+        self.patents = PatentsResource(self._http)
+
+        # Monitoring
+        self.events = EventsResource(self._http)
+        self.monitors = MonitorsResource(self._http)
+        self.webhooks = WebhooksResource(self._http)
+
+    # ------------------------------------------------------------------ meta
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    def account(self) -> Page:
+        """Plan and remaining credits for the configured API key (``/v1/account``)."""
+        return self._http.request("GET", "/v1/account")
+
+    def sources(self) -> Page:
+        """Dataset catalog + freshness (``/v1/sources``; no auth required)."""
+        return self._http.request("GET", "/v1/sources")
+
+    # ----------------------------------------------------------- grounded Q&A
+    def answer(
+        self,
+        q: str,
+        *,
+        cik: Optional[str] = None,
+        ticker: Optional[str] = None,
+        accession: Optional[str] = None,
+        forms: Optional[str] = None,
+        max_sources: Optional[int] = None,
+        output_schema: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> dict:
+        """Grounded Q&A over SEC filings (``POST /v1/answer``).
+
+        Returns the raw JSON answer envelope (answer text + cited sources).
+        """
+        body = {
+            k: v
+            for k, v in dict(
+                q=q, cik=cik, ticker=ticker, accession=accession, forms=forms,
+                max_sources=max_sources, output_schema=output_schema, **extra,
+            ).items()
+            if v is not None
+        }
+        return self._http.request("POST", "/v1/answer", body=body, raw=True)
+
+    def briefing(self, accession: str, **extra: Any) -> Page:
+        """AI briefing for one filing (``/v1/filings/{accession}/briefing``)."""
+        return self.filings.briefing(accession, **extra)
+
+    # -------------------------------------------------- OpenAI-compatible chat
+    def chat(self, *, model: str = "clous", messages: list, **kwargs: Any) -> dict:
+        """OpenAI-compatible chat completion (``POST /v1/chat/completions``).
+
+        Returns the raw OpenAI-style completion JSON. For drop-in use with the
+        ``openai`` SDK instead, point it at ``base_url="https://api.clous.ai/v1"``
+        with ``model="clous"``.
+        """
+        body = {"model": model, "messages": messages, **kwargs}
+        return self._http.request("POST", "/v1/chat/completions", body=body, raw=True)
+
+    # --------------------------------------------------------------- low-level
+    def get(self, path: str, *, params: Optional[Mapping[str, Any]] = None, raw: bool = False) -> Any:
+        """Escape hatch: issue a raw GET against any API path."""
+        return self._http.request("GET", path, params=params, raw=raw)
+
+    def post(self, path: str, *, body: Any = None, raw: bool = False) -> Any:
+        """Escape hatch: issue a raw POST against any API path."""
+        return self._http.request("POST", path, body=body, raw=raw)
+
+    # --------------------------------------------------------------- lifecycle
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Clous":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()