knowledge2 0.4.0__py3-none-any.whl

sdk/_base.py

@@ -0,0 +1,541 @@
+"""Base HTTP client for the Knowledge2 SDK.
+
+Provides :class:`BaseClient` which handles HTTP transport, automatic
+retries with exponential backoff, error classification, pagination,
+and debug logging.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+from sdk._paging import Page, SyncPager
+from sdk._raw_response import RawResponse
+from sdk._validation_response import maybe_validate
+
+try:  # Python 3.11+
+    from typing import Self
+except ImportError:  # pragma: no cover - Python < 3.11
+    from typing_extensions import Self
+
+import httpx
+
+from sdk._logging import _redact_headers, logger
+from sdk._transport import build_auth_headers, calculate_backoff, error_from_response
+from sdk._version import __version__
+from sdk.errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    Knowledge2Error,
+    RateLimitError,
+)
+
+if TYPE_CHECKING:
+    from sdk._request_options import RequestOptions
+
+
+@dataclass
+class ClientTimeouts:
+    """Per-phase HTTP timeout configuration.
+
+    All values are in seconds.  ``None`` means no limit for that phase.
+    """
+
+    connect: float | None = 5.0
+    read: float | None = 60.0
+    write: float | None = 30.0
+    pool: float | None = 10.0
+
+
+@dataclass
+class ClientLimits:
+    """HTTP connection pool limits for the SDK client."""
+
+    max_connections: int = 20
+    max_keepalive_connections: int = 10
+    keepalive_expiry: float = 30.0
+
+
+class BaseClient:
+    @staticmethod
+    def _normalize_base_url(base_url: str) -> str:
+        """Normalize and validate base URL input before constructing httpx.Client."""
+        normalized = base_url.strip().rstrip("/")
+        if not normalized:
+            raise ValueError("api_host must not be empty")
+
+        for idx, char in enumerate(normalized):
+            if ord(char) < 32 or ord(char) == 127:
+                escaped = repr(char).strip("'")
+                raise ValueError(
+                    f"api_host contains invalid control character {escaped} at position {idx}"
+                )
+        return normalized
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None,
+        *,
+        bearer_token: str | None = None,
+        bearer_token_factory: Callable[[], str] | None = None,
+        token_cache_ttl: float = 300.0,
+        admin_token: str | None = None,
+        headers: dict[str, str] | None = None,
+        user_agent: str | None = None,
+        timeout: float | ClientTimeouts | httpx.Timeout | None = None,
+        limits: ClientLimits | None = None,
+        max_retries: int = 2,
+        validate_responses: bool = False,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if bearer_token and bearer_token_factory:
+            raise ValueError("Cannot specify both 'bearer_token' and 'bearer_token_factory'")
+
+        self.base_url = self._normalize_base_url(base_url)
+        self.api_key = api_key
+        self.bearer_token = bearer_token
+        self.admin_token = admin_token
+        self._bearer_token_factory = bearer_token_factory
+        self._token_cache_ttl = token_cache_ttl
+        self._cached_token: str | None = None
+        self._token_expires_at: float = 0.0
+        self._token_lock = threading.Lock()
+        self._default_headers = dict(headers or {})
+        self._user_agent = user_agent or f"k2-python-sdk/{__version__}"
+        self._max_retries = max_retries
+        self._backoff_factor = 0.5
+        self._backoff_max = 8.0
+        self._validate_responses = validate_responses
+        self._raw_response_flag: threading.local = threading.local()
+
+        if http_client is not None:
+            # Caller-supplied client — SDK does NOT own it.
+            self._client = http_client
+            self._owns_http_client = False
+            if timeout is not None or limits is not None:
+                logger.warning(
+                    "When a caller-supplied http_client is provided, the SDK-level "
+                    "'timeout' and 'limits' parameters are ignored. Configure these "
+                    "settings on your httpx.Client instance directly."
+                )
+        else:
+            # SDK constructs and owns the client.
+            self._owns_http_client = True
+
+            # Resolve ClientTimeouts → httpx.Timeout
+            if isinstance(timeout, ClientTimeouts):
+                resolved_timeout: float | httpx.Timeout | None = httpx.Timeout(
+                    connect=timeout.connect,
+                    read=timeout.read,
+                    write=timeout.write,
+                    pool=timeout.pool,
+                )
+            else:
+                resolved_timeout = timeout
+
+            # Build httpx.Client with optional limits
+            client_kwargs: dict[str, Any] = {
+                "base_url": self.base_url,
+                "timeout": resolved_timeout,
+            }
+            if limits is not None:
+                client_kwargs["limits"] = httpx.Limits(
+                    max_connections=limits.max_connections,
+                    max_keepalive_connections=limits.max_keepalive_connections,
+                    keepalive_expiry=limits.keepalive_expiry,
+                )
+
+            self._client = httpx.Client(**client_kwargs)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client.
+
+        If the ``httpx.Client`` was supplied by the caller, this method
+        is a no-op — the caller retains ownership and responsibility
+        for closing it.
+        """
+        if self._owns_http_client:
+            self._client.close()
+
+    # ------------------------------------------------------------------
+    # Response validation
+    # ------------------------------------------------------------------
+
+    def _maybe_validate(self, data: Any, model_name: str) -> Any:
+        """Validate response data through its Pydantic model if validation is enabled."""
+        return maybe_validate(
+            data, model_name, validate=self._validate_responses, raw_response_cls=RawResponse
+        )
+
+    # ------------------------------------------------------------------
+    # Token factory helpers
+    # ------------------------------------------------------------------
+
+    def _resolve_bearer_token(self) -> str | None:
+        """Return the current bearer token, calling the factory if needed."""
+        if self.bearer_token:
+            return self.bearer_token
+        if self._bearer_token_factory is None:
+            return None
+
+        now = time.monotonic()
+        if self._cached_token is not None and now < self._token_expires_at:
+            return self._cached_token
+
+        with self._token_lock:
+            # Double-check after acquiring lock
+            now = time.monotonic()
+            if self._cached_token is not None and now < self._token_expires_at:
+                return self._cached_token
+            token = self._bearer_token_factory()
+            self._cached_token = token
+            if self._token_cache_ttl > 0:
+                self._token_expires_at = now + self._token_cache_ttl
+            else:
+                # TTL=0 means no caching — expire immediately
+                self._token_expires_at = 0.0
+            return token
+
+    def _clear_token_cache(self) -> None:
+        """Clear the cached bearer token (e.g. after a 401)."""
+        with self._token_lock:
+            self._cached_token = None
+            self._token_expires_at = 0.0
+
+    # ------------------------------------------------------------------
+    # Header helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        resolved_token = self._resolve_bearer_token()
+        return build_auth_headers(
+            api_key=self.api_key,
+            bearer_token=resolved_token,
+            admin_token=self.admin_token,
+            user_agent=self._user_agent,
+            default_headers=self._default_headers,
+            extra=extra,
+        )
+
+    @staticmethod
+    def _idempotency_headers(idempotency_key: str | None) -> dict[str, str]:
+        if not idempotency_key:
+            return {}
+        return {"Idempotency-Key": idempotency_key}
+
+    # ------------------------------------------------------------------
+    # Retry helpers
+    # ------------------------------------------------------------------
+
+    def _backoff_delay(self, attempt: int, error: Knowledge2Error | None = None) -> float:
+        """Calculate backoff delay with jitter for retry attempt *attempt*."""
+        return calculate_backoff(
+            attempt,
+            error,
+            backoff_factor=self._backoff_factor,
+            backoff_max=self._backoff_max,
+        )
+
+    # ------------------------------------------------------------------
+    # Core request with retry
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+        request_options: RequestOptions | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Send an HTTP request with automatic retry on transient failures.
+
+        Args:
+            method: HTTP method.
+            path: API path.
+            headers: Extra headers for this request.
+            request_options: Per-call overrides for timeout, retries,
+                and passthrough headers.
+            **kwargs: Forwarded to ``httpx.Client.request()``.
+        """
+        # Resolve per-call overrides from RequestOptions
+        effective_retries = self._max_retries
+        if request_options is not None:
+            if request_options.max_retries is not None:
+                effective_retries = request_options.max_retries
+            if request_options.timeout is not None:
+                ct = request_options.timeout
+                kwargs["timeout"] = httpx.Timeout(
+                    connect=ct.connect,
+                    read=ct.read,
+                    write=ct.write,
+                    pool=ct.pool,
+                )
+            if request_options.passthrough_headers:
+                headers = {**(headers or {}), **request_options.passthrough_headers}
+
+        last_error: Knowledge2Error | None = None
+        merged_headers = self._headers(headers)
+        return_raw = getattr(self._raw_response_flag, "enabled", False)
+
+        for attempt in range(1 + effective_retries):
+            try:
+                logger.debug(
+                    "%s %s (attempt %d/%d) headers=%s",
+                    method,
+                    path,
+                    attempt + 1,
+                    1 + effective_retries,
+                    _redact_headers(merged_headers),
+                )
+                response = self._client.request(method, path, headers=merged_headers, **kwargs)
+            except httpx.ConnectError as exc:
+                last_error = APIConnectionError(f"Connection error: {exc}")
+                last_error.__cause__ = exc
+                if attempt < effective_retries:
+                    delay = self._backoff_delay(attempt)
+                    logger.debug(
+                        "Retry %d/%d after %.2fs (connection error)",
+                        attempt + 1,
+                        effective_retries,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    continue
+                raise last_error from exc
+            except httpx.TimeoutException as exc:
+                last_error = APITimeoutError(f"Request timed out: {exc}")
+                last_error.__cause__ = exc
+                if attempt < effective_retries:
+                    delay = self._backoff_delay(attempt)
+                    logger.debug(
+                        "Retry %d/%d after %.2fs (timeout)",
+                        attempt + 1,
+                        effective_retries,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    continue
+                raise last_error from exc
+            except httpx.HTTPError as exc:
+                last_error = APIConnectionError(f"Transport error: {exc}")
+                last_error.__cause__ = exc
+                if attempt < effective_retries:
+                    delay = self._backoff_delay(attempt)
+                    logger.debug(
+                        "Retry %d/%d after %.2fs (transport error)",
+                        attempt + 1,
+                        effective_retries,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    continue
+                raise last_error from exc
+
+            logger.debug(
+                "%s %s → %d",
+                method,
+                path,
+                response.status_code,
+            )
+
+            if response.is_error:
+                error = self._error_from_response(response)
+                # Clear cached factory token on 401 so the next attempt
+                # (or next call) fetches a fresh token.
+                if response.status_code == 401 and self._bearer_token_factory:
+                    self._clear_token_cache()
+                if error.retryable and attempt < effective_retries:
+                    delay = self._backoff_delay(attempt, error)
+                    logger.debug(
+                        "Retry %d/%d after %.2fs (status %d)",
+                        attempt + 1,
+                        effective_retries,
+                        delay,
+                        response.status_code,
+                    )
+                    time.sleep(delay)
+                    last_error = error
+                    continue
+                if return_raw:
+                    # Wrap HTTP errors into RawResponse instead of raising
+                    # so callers can inspect status/headers/body.
+                    if response.content:
+                        try:
+                            error_parsed = response.json()
+                        except ValueError:
+                            error_parsed = response.text if response.text else None
+                    else:
+                        error_parsed = None
+                    return RawResponse(
+                        status_code=response.status_code,
+                        headers=dict(response.headers),
+                        parsed=error_parsed,
+                    )
+                raise error
+
+            # Success
+            if response.content:
+                try:
+                    parsed = response.json()
+                except ValueError as exc:
+                    raise APIConnectionError(
+                        f"Expected JSON response but got {response.headers.get('content-type', 'unknown')}: {exc}"
+                    ) from exc
+            else:
+                parsed = None
+            if return_raw:
+                return RawResponse(
+                    status_code=response.status_code,
+                    headers=dict(response.headers),
+                    parsed=parsed,
+                )
+            return parsed
+
+        # All retries exhausted — should not normally reach here because
+        # the last iteration raises, but satisfies the type checker.
+        if last_error is not None:  # pragma: no cover
+            raise last_error
+        return None  # pragma: no cover
+
+    # ------------------------------------------------------------------
+    # Job polling
+    # ------------------------------------------------------------------
+
+    def _wait_for_job(
+        self, job_id: str, *, poll_s: int = 5, timeout_s: float | None = None
+    ) -> dict[str, Any]:
+        # Temporarily disable raw response mode for internal polling calls
+        saved = getattr(self._raw_response_flag, "enabled", False)
+        self._raw_response_flag.enabled = False
+        try:
+            return self._wait_for_job_inner(job_id, poll_s=poll_s, timeout_s=timeout_s)
+        finally:
+            self._raw_response_flag.enabled = saved
+
+    def _wait_for_job_inner(
+        self, job_id: str, *, poll_s: int = 5, timeout_s: float | None = None
+    ) -> dict[str, Any]:
+        start = time.monotonic()
+        while True:
+            job = self._request("GET", f"/v1/jobs/{job_id}")
+            if not isinstance(job, dict):
+                raise RuntimeError(
+                    f"Unexpected response polling job {job_id}: {type(job).__name__}"
+                )
+            status = job.get("status")
+            if status in {"succeeded", "failed", "canceled"}:
+                if status != "succeeded":
+                    message = job.get("error_message") or f"Job {job_id} ended with status={status}"
+                    raise RuntimeError(message)
+                return job
+            if timeout_s is not None and (time.monotonic() - start) > timeout_s:
+                raise TimeoutError(f"Timed out waiting for job {job_id}")
+            time.sleep(poll_s)
+
+    # ------------------------------------------------------------------
+    # Pagination
+    # ------------------------------------------------------------------
+
+    def _list_page(
+        self,
+        method: str,
+        path: str,
+        *,
+        items_key: str,
+        params: dict[str, Any] | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> Page[dict[str, Any]]:
+        """Fetch a single page and return a Page object with metadata."""
+        page_params = {**(params or {}), "limit": limit, "offset": offset}
+        data = self._request(method, path, params=page_params)
+        response_meta: RawResponse[dict[str, Any] | list[Any] | None] | None = None
+        if isinstance(data, RawResponse):
+            response_meta = data
+            data = data.parsed
+
+        if isinstance(data, dict):
+            items = data.get(items_key, [])
+            total = data.get("total", len(items))
+        elif isinstance(data, list):
+            items = data
+            total = len(items)
+        else:
+            items = []
+            total = 0
+
+        page = Page(items=items, total=total, offset=offset, limit=limit)
+        if response_meta is not None:
+            return cast(
+                "Page[dict[str, Any]]",
+                RawResponse(
+                    status_code=response_meta.status_code,
+                    headers=response_meta.headers,
+                    parsed=page,
+                ),
+            )
+        return page
+
+    def _paginate(
+        self,
+        method: str,
+        path: str,
+        *,
+        items_key: str,
+        params: dict[str, Any] | None = None,
+        limit: int = 100,
+    ) -> SyncPager[dict[str, Any]]:
+        """Return a SyncPager for lazy multi-page iteration.
+
+        Pages are fetched on demand — the next page is requested only
+        when the current page's items are exhausted.
+
+        Args:
+            method: HTTP method (usually ``"GET"``).
+            path: API path (e.g. ``"/v1/corpora"``).
+            items_key: JSON key that contains the list of items in the
+                response (e.g. ``"items"``).
+            params: Extra query parameters forwarded to each page
+                request.
+            limit: Page size (default 100).
+        """
+        base_params = dict(params or {})
+
+        def fetch_page(offset: int, page_limit: int) -> tuple[list[dict[str, Any]], int]:
+            page_params = {**base_params, "limit": page_limit, "offset": offset}
+            data = self._request(method, path, params=page_params)
+            if isinstance(data, dict):
+                items = data.get(items_key, [])
+                total = data.get("total", len(items))
+            elif isinstance(data, list):
+                items = data
+                total = len(items)
+            else:
+                items = []
+                total = 0
+            return items, total
+
+        return SyncPager(fetch_page, limit=limit)
+
+    # ------------------------------------------------------------------
+    # Error classification
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _error_from_response(response: httpx.Response) -> APIError:
+        """Parse an error response into the appropriate :class:`APIError` subclass."""
+        return error_from_response(response)

sdk/_logging.py

@@ -0,0 +1,41 @@
+"""Logging utilities for the Knowledge2 SDK.
+
+The SDK uses a logger named ``knowledge2``.  By default no handlers are
+attached (standard library convention) — consumers configure logging as
+they see fit.  :func:`set_debug` is a convenience shortcut that adds a
+``StreamHandler`` with ``DEBUG`` level.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("knowledge2")
+
+_REDACT_HEADERS: frozenset[str] = frozenset({"x-api-key", "authorization", "x-admin-token"})
+
+
+def _redact_headers(headers: dict[str, str]) -> dict[str, str]:
+    """Return a copy of *headers* with auth values replaced by ``***``."""
+    return {k: ("***" if k.lower() in _REDACT_HEADERS else v) for k, v in headers.items()}
+
+
+def set_debug(enabled: bool = True) -> None:
+    """Enable or disable SDK debug logging to stderr.
+
+    Args:
+        enabled: When *True*, adds a ``StreamHandler`` at ``DEBUG`` level
+            to the ``knowledge2`` logger.  When *False*, removes all
+            handlers and resets the level.
+    """
+    if enabled:
+        if not logger.handlers:
+            handler = logging.StreamHandler()
+            handler.setFormatter(
+                logging.Formatter("%(asctime)s %(name)s %(levelname)s %(message)s")
+            )
+            logger.addHandler(handler)
+        logger.setLevel(logging.DEBUG)
+    else:
+        logger.handlers.clear()
+        logger.setLevel(logging.WARNING)

sdk/_paging.py

@@ -0,0 +1,73 @@
+"""Pagination primitives for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Generic, Iterator, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """A single page of results with pagination metadata."""
+
+    items: list[T]
+    total: int
+    offset: int
+    limit: int
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __bool__(self) -> bool:
+        return len(self.items) > 0
+
+
+class SyncPager(Generic[T]):
+    """Stateful paginator that lazily fetches pages.
+
+    Hides whether underlying pagination is offset- or cursor-based.
+    """
+
+    def __init__(
+        self,
+        fetch_page: Callable[[int, int], tuple[list[T], int]],
+        *,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> None:
+        self._fetch_page = fetch_page
+        self._limit = limit
+        self._offset = offset
+        self._exhausted = False
+
+    def next_page(self) -> Page[T] | None:
+        """Fetch the next page. Returns None when exhausted."""
+        if self._exhausted:
+            return None
+        items, total = self._fetch_page(self._offset, self._limit)
+        page = Page(items=items, total=total, offset=self._offset, limit=self._limit)
+        if len(items) < self._limit or (total > len(items) and self._offset + self._limit >= total):
+            self._exhausted = True
+        else:
+            self._offset += self._limit
+        return page
+
+    def iter_pages(self) -> Iterator[Page[T]]:
+        """Iterate over all pages."""
+        while True:
+            page = self.next_page()
+            if page is None:
+                break
+            yield page
+            if not page.items:
+                break
+
+    def __iter__(self) -> Iterator[T]:
+        """Item-level iteration across all pages."""
+        for page in self.iter_pages():
+            yield from page.items