knowledge2 0.4.0__py3-none-any.whl

knowledge2-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (79.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

knowledge2-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sdk

sdk/__init__.py

@@ -0,0 +1,70 @@
+"""Knowledge2 Python SDK."""
+
+from sdk._version import __version__
+
+from ._async_paging import AsyncPager
+from ._base import ClientLimits, ClientTimeouts
+from ._logging import set_debug
+from ._paging import Page, SyncPager
+from ._raw_response import RawResponse
+from ._request_options import RequestOptions
+from .async_client import AsyncKnowledge2
+from .client import Knowledge2, Knowledge2Validated
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConfirmationRequiredError,
+    ConflictError,
+    Knowledge2Error,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .resources.pipeline_builder import PipelineBuilder
+
+# K2Config is lazily imported to keep pydantic-settings optional.
+# Users who don't need K2Config never import pydantic-settings.
+
+
+def __getattr__(name: str):
+    if name == "K2Config":
+        from .config import K2Config
+
+        return K2Config
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncKnowledge2",
+    "AsyncPager",
+    "AuthenticationError",
+    "BadRequestError",
+    "ClientLimits",
+    "ClientTimeouts",
+    "ConfirmationRequiredError",
+    "ConflictError",
+    "K2Config",
+    "Knowledge2",
+    "Knowledge2Error",
+    "Knowledge2Validated",
+    "NotFoundError",
+    "Page",
+    "PermissionDeniedError",
+    "PipelineBuilder",
+    "RateLimitError",
+    "RawResponse",
+    "RequestOptions",
+    "ServerError",
+    "SyncPager",
+    "ValidationError",
+    "__version__",
+    "set_debug",
+]

sdk/_async_base.py

@@ -0,0 +1,525 @@
+"""Async base HTTP client for the Knowledge2 SDK.
+
+Provides :class:`AsyncBaseClient` which handles HTTP transport, automatic
+retries with exponential backoff, error classification, pagination,
+and debug logging — mirroring :class:`BaseClient` for async contexts.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import time
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, cast
+
+import httpx
+
+from sdk._async_paging import AsyncPager
+from sdk._base import ClientLimits, ClientTimeouts
+from sdk._logging import _redact_headers, logger
+from sdk._paging import Page
+from sdk._raw_response import RawResponse
+from sdk._transport import build_auth_headers, calculate_backoff, error_from_response
+from sdk._validation_response import maybe_validate
+from sdk._version import __version__
+from sdk.errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    Knowledge2Error,
+    RateLimitError,
+)
+
+if TYPE_CHECKING:
+    from sdk._request_options import RequestOptions
+
+try:  # Python 3.11+
+    from typing import Self
+except ImportError:  # pragma: no cover - Python < 3.11
+    from typing_extensions import Self
+
+
+class AsyncBaseClient:
+    @staticmethod
+    def _normalize_base_url(base_url: str) -> str:
+        """Normalize and validate base URL input before constructing httpx.AsyncClient."""
+        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.AsyncClient | 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 = asyncio.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: contextvars.ContextVar[bool] = contextvars.ContextVar(
+            "raw_response_flag", default=False
+        )
+
+        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.AsyncClient 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.AsyncClient(**client_kwargs)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client.
+
+        If the ``httpx.AsyncClient`` was supplied by the caller, this
+        method is a no-op — the caller retains ownership.
+        """
+        if self._owns_http_client:
+            await self._client.aclose()
+
+    # ------------------------------------------------------------------
+    # 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
+    # ------------------------------------------------------------------
+
+    async 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
+
+        async 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
+            # Factory might be sync — run in a thread to avoid blocking the loop
+            token = await asyncio.to_thread(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
+
+    async def _clear_token_cache(self) -> None:
+        """Clear the cached bearer token (e.g. after a 401)."""
+        async with self._token_lock:
+            self._cached_token = None
+            self._token_expires_at = 0.0
+
+    # ------------------------------------------------------------------
+    # Header helpers
+    # ------------------------------------------------------------------
+
+    async def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        resolved_token = await 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
+    # ------------------------------------------------------------------
+
+    async 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.AsyncClient.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
+        return_raw = self._raw_response_flag.get(False)
+
+        for attempt in range(1 + effective_retries):
+            merged_headers = await self._headers(headers)
+            try:
+                logger.debug(
+                    "%s %s (attempt %d/%d) headers=%s",
+                    method,
+                    path,
+                    attempt + 1,
+                    1 + effective_retries,
+                    _redact_headers(merged_headers),
+                )
+                response = await self._client.request(
+                    method, path, headers=merged_headers, **kwargs
+                )
+            except asyncio.CancelledError:
+                raise
+            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,
+                    )
+                    await asyncio.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,
+                    )
+                    await asyncio.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,
+                    )
+                    await asyncio.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:
+                    await 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,
+                    )
+                    await asyncio.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
+    # ------------------------------------------------------------------
+
+    async 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
+        token = self._raw_response_flag.set(False)
+        try:
+            return await self._wait_for_job_inner(job_id, poll_s=poll_s, timeout_s=timeout_s)
+        finally:
+            self._raw_response_flag.reset(token)
+
+    async 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 = await 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}")
+            await asyncio.sleep(poll_s)
+
+    # ------------------------------------------------------------------
+    # Pagination
+    # ------------------------------------------------------------------
+
+    async 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 = await 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,
+    ) -> AsyncPager[dict[str, Any]]:
+        """Return an AsyncPager 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 {})
+
+        async def fetch_page(offset: int, page_limit: int) -> tuple[list[dict[str, Any]], int]:
+            page_params = {**base_params, "limit": page_limit, "offset": offset}
+            data = await 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 AsyncPager(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/_async_paging.py

@@ -0,0 +1,57 @@
+"""Async pagination primitives for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Generic, TypeVar
+
+from sdk._paging import Page
+
+T = TypeVar("T")
+
+
+class AsyncPager(Generic[T]):
+    """Async stateful paginator that lazily fetches pages."""
+
+    def __init__(
+        self,
+        fetch_page: Callable[[int, int], Awaitable[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
+
+    async def next_page(self) -> Page[T] | None:
+        """Fetch the next page. Returns None when exhausted."""
+        if self._exhausted:
+            return None
+        items, total = await 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
+
+    async def iter_pages(self) -> AsyncIterator[Page[T]]:
+        """Iterate over all pages."""
+        while True:
+            page = await self.next_page()
+            if page is None:
+                break
+            yield page
+            if not page.items:
+                break
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        """Item-level iteration across all pages."""
+        return self._item_iterator()
+
+    async def _item_iterator(self) -> AsyncIterator[T]:
+        async for page in self.iter_pages():
+            for item in page.items:
+                yield item