knowledge2 0.4.0__py3-none-any.whl

sdk/_preview.py

@@ -0,0 +1,70 @@
+"""Decorator for marking SDK resource classes as preview features."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import warnings
+from typing import Any, TypeVar
+
+_warned: set[str] = set()
+
+_T = TypeVar("_T", bound=type)
+
+
+def preview_resource(cls: _T) -> _T:
+    """Class decorator that wraps public methods to emit a one-shot RuntimeWarning.
+
+    The warning fires once per method name per process, alerting callers
+    that the resource requires a server-side feature flag.
+
+    Properties and private/dunder methods are left untouched.
+    """
+    for name, attr in list(vars(cls).items()):
+        if name.startswith("_"):
+            continue
+        if isinstance(attr, (property, classmethod, staticmethod)):
+            continue
+        if not callable(attr):
+            continue
+
+        fn = attr
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(
+                *args: Any, _fn: Any = fn, _name: str = name, **kwargs: Any
+            ) -> Any:
+                key = f"{_fn.__qualname__}"
+                if key not in _warned:
+                    _warned.add(key)
+                    warnings.warn(
+                        f"{_name}() is a preview feature and may not be available "
+                        f"in all environments. The underlying API requires a "
+                        f"feature flag to be enabled.",
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
+                return await _fn(*args, **kwargs)
+
+            setattr(cls, name, async_wrapper)
+        else:
+
+            @functools.wraps(fn)
+            def sync_wrapper(*args: Any, _fn: Any = fn, _name: str = name, **kwargs: Any) -> Any:
+                key = f"{_fn.__qualname__}"
+                if key not in _warned:
+                    _warned.add(key)
+                    warnings.warn(
+                        f"{_name}() is a preview feature and may not be available "
+                        f"in all environments. The underlying API requires a "
+                        f"feature flag to be enabled.",
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
+                return _fn(*args, **kwargs)
+
+            setattr(cls, name, sync_wrapper)
+
+    return cls

sdk/_raw_response.py

@@ -0,0 +1,25 @@
+"""Raw HTTP response wrapper for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class RawResponse(Generic[T]):
+    """Typed wrapper exposing HTTP-level details alongside the parsed body.
+
+    Returned by ``client.with_raw_response.<method>(...)``.
+
+    Attributes:
+        status_code: HTTP status code (e.g. 200, 201).
+        headers: Response headers as a plain dict.
+        parsed: The same typed result the normal method would return.
+    """
+
+    status_code: int
+    headers: dict[str, str]
+    parsed: T

sdk/_request_options.py

@@ -0,0 +1,51 @@
+"""Per-call request options for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sdk._base import ClientTimeouts
+
+_BLOCKED_HEADERS = frozenset(
+    {
+        "authorization",
+        "content-type",
+        "accept",
+        "content-length",
+        "x-api-key",
+        "x-admin-token",
+        "user-agent",
+    }
+)
+
+
+@dataclass(frozen=True)
+class RequestOptions:
+    """Per-call overrides for timeout, retry, and passthrough headers.
+
+    Any field left as ``None`` inherits the client-level default.
+
+    Args:
+        timeout: Override the client-level :class:`ClientTimeouts` for
+            this single call.
+        max_retries: Override the client-level ``max_retries`` for this
+            single call.
+        passthrough_headers: Non-semantic headers (e.g. ``X-Request-ID``,
+            ``X-Correlation-ID``) forwarded verbatim.  SDK-managed headers
+            (``Authorization``, ``Content-Type``, ``X-API-Key``, etc.)
+            raise :class:`ValueError` if supplied.
+    """
+
+    timeout: ClientTimeouts | None = None
+    max_retries: int | None = None
+    passthrough_headers: dict[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        if self.passthrough_headers:
+            for name in self.passthrough_headers:
+                if name.lower() in _BLOCKED_HEADERS:
+                    raise ValueError(
+                        f"Header {name!r} is managed by the SDK and cannot be "
+                        f"set via passthrough_headers. "
+                        f"Blocked headers: {sorted(_BLOCKED_HEADERS)}"
+                    )

sdk/_transport.py

@@ -0,0 +1,144 @@
+"""Shared transport helpers for sync and async HTTP clients.
+
+All functions are stateless and side-effect-free (except logging).
+They are extracted from :class:`BaseClient` so that
+:class:`AsyncBaseClient` can reuse the same logic without duplication.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import random
+from typing import Any
+
+import httpx
+
+from sdk.errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    Knowledge2Error,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+# Status codes that map to specific error subclasses.
+_STATUS_ERROR_MAP: dict[int, type[APIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+    500: ServerError,
+    502: ServerError,
+    503: ServerError,
+    504: ServerError,
+}
+
+
+def error_from_response(response: httpx.Response) -> APIError:
+    """Parse an error response into the appropriate APIError subclass."""
+    request_id = response.headers.get("X-Request-Id")
+    code: str | None = None
+    details: Any = None
+    message = response.text or response.reason_phrase or "Unknown error"
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+    if isinstance(payload, dict):
+        error = payload.get("error")
+        if isinstance(error, dict):
+            code = error.get("code")
+            details = error.get("details")
+            request_id = error.get("request_id") or request_id
+            message = error.get("message") or message
+        elif "detail" in payload:
+            detail = payload.get("detail")
+            if isinstance(detail, str):
+                message = detail
+            else:
+                details = detail
+    if request_id:
+        message = f"{message} (request_id={request_id})"
+
+    status = response.status_code
+    error_cls = _STATUS_ERROR_MAP.get(status)
+    if error_cls is None:
+        error_cls = ServerError if 500 <= status < 600 else APIError
+
+    if error_cls is RateLimitError:
+        retry_after_raw = response.headers.get("Retry-After")
+        retry_after: float | None = None
+        if retry_after_raw is not None:
+            with contextlib.suppress(ValueError, TypeError):
+                retry_after = float(retry_after_raw)
+        return RateLimitError(
+            message,
+            status_code=status,
+            retry_after=retry_after,
+            code=code,
+            details=details,
+            request_id=request_id,
+        )
+
+    return error_cls(
+        message,
+        status_code=status,
+        code=code,
+        details=details,
+        request_id=request_id,
+    )
+
+
+def calculate_backoff(
+    attempt: int,
+    error: Knowledge2Error | None,
+    *,
+    backoff_factor: float = 0.5,
+    backoff_max: float = 8.0,
+) -> float:
+    """Calculate exponential backoff delay with jitter."""
+    if isinstance(error, RateLimitError) and error.retry_after is not None:
+        return error.retry_after
+    base = backoff_factor * (2**attempt)
+    jitter = random.random() * 0.25 * base
+    return min(base + jitter, backoff_max)
+
+
+def build_auth_headers(
+    *,
+    api_key: str | None,
+    bearer_token: str | None,
+    admin_token: str | None,
+    user_agent: str,
+    default_headers: dict[str, str],
+    extra: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Assemble request headers with auth credentials."""
+    headers = dict(default_headers)
+    extra_headers = extra if extra is not None else {}
+    if api_key:
+        headers["X-API-Key"] = api_key
+        if "X-API-Key" in extra_headers:
+            extra_headers["X-API-Key"] = api_key
+    if bearer_token:
+        bearer_value = f"Bearer {bearer_token}"
+        headers["Authorization"] = bearer_value
+        if "Authorization" in extra_headers:
+            extra_headers["Authorization"] = bearer_value
+    if admin_token:
+        headers["X-Admin-Token"] = admin_token
+        if "X-Admin-Token" in extra_headers:
+            extra_headers["X-Admin-Token"] = admin_token
+    if user_agent and "User-Agent" not in headers and "User-Agent" not in extra_headers:
+        headers["User-Agent"] = user_agent
+    if extra_headers:
+        headers.update(extra_headers)
+    return headers

sdk/_validation.py

@@ -0,0 +1,25 @@
+"""Parameter validation utilities for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+
+def require_str(value: str, name: str) -> str:
+    """Validate that a required string parameter is non-empty.
+
+    Strips whitespace and raises :class:`ValueError` if the result is
+    empty.  Returns the stripped value for use as the canonical form.
+
+    Args:
+        value: The parameter value to validate.
+        name: The parameter name (used in the error message).
+
+    Returns:
+        The stripped, non-empty string.
+
+    Raises:
+        ValueError: If *value* is not a string or is empty/whitespace-only.
+    """
+    stripped = value.strip() if isinstance(value, str) else ""
+    if not stripped:
+        raise ValueError(f"'{name}' must be a non-empty string, got {value!r}")
+    return stripped

sdk/_validation_response.py

@@ -0,0 +1,36 @@
+"""Shared response validation logic for sync and async clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def maybe_validate(data: Any, model_name: str, *, validate: bool, raw_response_cls: type) -> Any:
+    """Validate response data through its Pydantic model if validation is enabled.
+
+    Args:
+        data: The raw dict from ``_request()``.
+        model_name: The TypedDict class name (e.g. ``"SearchResponse"``).
+        validate: Whether response validation is enabled.
+        raw_response_cls: The RawResponse class to check against.
+
+    Returns:
+        The validated Pydantic model instance if validation is on,
+        otherwise the raw dict unchanged.
+    """
+    if isinstance(data, raw_response_cls):
+        return data
+    if not validate or data is None:
+        return data
+    try:
+        from sdk.models._registry import get_model_for_type
+    except ImportError as exc:
+        raise ImportError(
+            "Response validation requires the optional 'pydantic' dependency. "
+            "Install with: pip install 'knowledge2[pydantic]'"
+        ) from exc
+
+    model_cls = get_model_for_type(model_name)
+    if model_cls is None:
+        return data
+    return model_cls.model_validate(data)  # type: ignore[attr-defined]

sdk/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the SDK version string."""
+
+__version__ = "0.4.0"

sdk/async_client.py

@@ -0,0 +1,320 @@
+"""Async Knowledge2 API client.
+
+Usage::
+
+    from sdk import AsyncKnowledge2
+
+    async with AsyncKnowledge2(api_key="k2_...") as client:
+        results = await client.search(corpus_id, "my query")
+
+    # Or use the async factory to auto-detect org_id:
+    client = await AsyncKnowledge2.create(api_key="k2_...")
+"""
+
+from __future__ import annotations
+
+import contextvars
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from sdk._async_base import AsyncBaseClient
+from sdk._base import ClientLimits, ClientTimeouts
+from sdk._logging import set_debug as _set_debug
+from sdk.async_resources import (
+    AsyncA2AMixin,
+    AsyncAgentsMixin,
+    AsyncAuditMixin,
+    AsyncAuthMixin,
+    AsyncConsoleMixin,
+    AsyncCorporaMixin,
+    AsyncDeploymentsMixin,
+    AsyncDocumentsMixin,
+    AsyncFeedsMixin,
+    AsyncIndexesMixin,
+    AsyncJobsMixin,
+    AsyncMetadataMixin,
+    AsyncModelsMixin,
+    AsyncOnboardingMixin,
+    AsyncOrgsMixin,
+    AsyncPipelinesMixin,
+    AsyncProjectsMixin,
+    AsyncSearchMixin,
+    AsyncTrainingMixin,
+    AsyncUsageMixin,
+)
+
+if TYPE_CHECKING:
+    from sdk.config import K2Config
+
+DEFAULT_API_HOST = "https://api.knowledge2.ai"
+
+_SENTINEL = object()
+
+
+class AsyncKnowledge2(
+    AsyncBaseClient,
+    AsyncOrgsMixin,
+    AsyncAuthMixin,
+    AsyncProjectsMixin,
+    AsyncCorporaMixin,
+    AsyncModelsMixin,
+    AsyncDocumentsMixin,
+    AsyncIndexesMixin,
+    AsyncSearchMixin,
+    AsyncMetadataMixin,
+    AsyncTrainingMixin,
+    AsyncDeploymentsMixin,
+    AsyncJobsMixin,
+    AsyncAuditMixin,
+    AsyncUsageMixin,
+    AsyncConsoleMixin,
+    AsyncOnboardingMixin,
+    AsyncAgentsMixin,
+    AsyncFeedsMixin,
+    AsyncPipelinesMixin,
+    AsyncA2AMixin,
+):
+    """Async Knowledge2 API client.
+
+    The async variant of :class:`~sdk.client.Knowledge2`.  Supports
+    ``async with`` context management and ``await``-based API calls.
+
+    Note: ``org_id`` auto-detection requires an async network call, so
+    it cannot happen in ``__init__``.  Use :meth:`create` for automatic
+    ``org_id`` resolution.
+
+    Args:
+        config: Optional :class:`~sdk.config.K2Config` instance.
+        api_host: Base URL of the Knowledge2 API.
+        api_key: API key for authentication (``X-API-Key`` header).
+        org_id: Organisation ID.  Use :meth:`create` for auto-detection.
+        bearer_token: Bearer token for console / Auth0 authentication.
+        bearer_token_factory: Callable returning a bearer token string.
+        token_cache_ttl: Seconds to cache the factory-produced token.
+        admin_token: Admin token (``X-Admin-Token`` header).
+        headers: Extra default headers sent with every request.
+        user_agent: Custom ``User-Agent`` header value.
+        timeout: Request timeout in seconds (or an ``httpx.Timeout``).
+        limits: Connection pool limits.
+        max_retries: Maximum number of automatic retries.
+        validate_responses: Enable Pydantic response validation.
+        http_client: Pre-configured ``httpx.AsyncClient``.  When
+            supplied the SDK does **not** close it — the caller retains
+            ownership.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: K2Config | None = None,
+        api_host: str | object = _SENTINEL,
+        api_key: str | None | object = _SENTINEL,
+        org_id: str | None | object = _SENTINEL,
+        bearer_token: str | None | object = _SENTINEL,
+        bearer_token_factory: Callable[[], str] | None = None,
+        token_cache_ttl: float = 300.0,
+        admin_token: str | None | object = _SENTINEL,
+        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 | object = _SENTINEL,
+        validate_responses: bool | object = _SENTINEL,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        # Resolve config vs explicit kwargs (explicit kwargs win)
+        resolved_api_host: str = DEFAULT_API_HOST
+        resolved_api_key: str | None = None
+        resolved_org_id: str | None = None
+        resolved_bearer_token: str | None = None
+        resolved_admin_token: str | None = None
+        resolved_max_retries: int = 2
+        resolved_validate_responses: bool = False
+
+        if config is not None:
+            resolved_api_host = str(config.api_host)
+            resolved_api_key = config.api_key
+            resolved_org_id = config.org_id
+            resolved_bearer_token = config.bearer_token
+            resolved_admin_token = config.admin_token
+            resolved_max_retries = config.max_retries
+            resolved_validate_responses = getattr(config, "validate_responses", False)
+            # Build timeout from config if no explicit timeout given
+            if timeout is None:
+                timeout = ClientTimeouts(
+                    connect=config.timeout_connect,
+                    read=config.timeout_read,
+                    write=config.timeout_write,
+                )
+            # Build limits from config if no explicit limits given
+            if limits is None:
+                limits = ClientLimits(
+                    max_connections=config.max_connections,
+                    max_keepalive_connections=config.max_keepalive_connections,
+                )
+
+        # Explicit kwargs override config
+        if api_host is not _SENTINEL:
+            resolved_api_host = api_host  # type: ignore[assignment]
+        if api_key is not _SENTINEL:
+            resolved_api_key = api_key  # type: ignore[assignment]
+        if org_id is not _SENTINEL:
+            resolved_org_id = org_id  # type: ignore[assignment]
+        if bearer_token is not _SENTINEL:
+            resolved_bearer_token = bearer_token  # type: ignore[assignment]
+        if admin_token is not _SENTINEL:
+            resolved_admin_token = admin_token  # type: ignore[assignment]
+        if max_retries is not _SENTINEL:
+            resolved_max_retries = max_retries  # type: ignore[assignment]
+        if validate_responses is not _SENTINEL:
+            resolved_validate_responses = validate_responses  # type: ignore[assignment]
+
+        super().__init__(
+            resolved_api_host,
+            resolved_api_key,
+            bearer_token=resolved_bearer_token,
+            bearer_token_factory=bearer_token_factory,
+            token_cache_ttl=token_cache_ttl,
+            admin_token=resolved_admin_token,
+            headers=headers,
+            user_agent=user_agent,
+            timeout=timeout,
+            limits=limits,
+            max_retries=resolved_max_retries,
+            validate_responses=resolved_validate_responses,
+            http_client=http_client,
+        )
+        self.org_id = resolved_org_id
+
+    # ------------------------------------------------------------------
+    # Async factory
+    # ------------------------------------------------------------------
+
+    @classmethod
+    async def create(cls, *, lazy: bool = False, **kwargs: Any) -> AsyncKnowledge2:
+        """Create an async client with automatic org_id detection.
+
+        Equivalent to constructing the client and then calling
+        ``get_whoami()`` to resolve the org_id when an API key is
+        provided but no org_id is given.
+
+        All keyword arguments are forwarded to :class:`AsyncKnowledge2`.
+
+        Args:
+            lazy: When ``True``, skip the automatic
+                ``GET /v1/auth/whoami`` call.  ``org_id`` will remain
+                ``None`` unless provided explicitly or resolved later
+                via :meth:`get_whoami`.  Defaults to ``False``.
+            **kwargs: Forwarded to :class:`AsyncKnowledge2`.
+        """
+        client = cls(**kwargs)
+        if not lazy and client.org_id is None and client.api_key is not None:
+            whoami = await client.get_whoami()
+            client.org_id = whoami["org_id"] if isinstance(whoami, dict) else whoami.org_id  # type: ignore[attr-defined]
+        return client
+
+    # ------------------------------------------------------------------
+    # Factory classmethods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    async def from_env(cls, **overrides: Any) -> AsyncKnowledge2:
+        """Create a client from ``K2_*`` environment variables.
+
+        Equivalent to ``AsyncKnowledge2.create(config=K2Config())``.
+        """
+        from sdk.config import K2Config
+
+        config = K2Config()
+        return await cls.create(config=config, **overrides)
+
+    @classmethod
+    async def from_file(cls, path: str | Path, **overrides: Any) -> AsyncKnowledge2:
+        """Create a client from a JSON or YAML config file.
+
+        Args:
+            path: Path to the configuration file.
+            **overrides: K2Config field values that override file values.
+        """
+        from sdk.config import K2Config
+
+        config = K2Config.from_file(path, **overrides)
+        return await cls.create(config=config)
+
+    @classmethod
+    async def from_profile(
+        cls,
+        name: str,
+        path: str | Path | None = None,
+        **overrides: Any,
+    ) -> AsyncKnowledge2:
+        """Create a client from a named profile in a config file.
+
+        Args:
+            name: Profile key to load (e.g. ``"staging"``).
+            path: Config file path. Defaults to ``~/.k2/config.yaml``.
+            **overrides: K2Config field values that override profile values.
+        """
+        from sdk.config import K2Config
+
+        config = K2Config.from_profile(name, path=path, **overrides)
+        return await cls.create(config=config)
+
+    # ------------------------------------------------------------------
+    # Auth & debug helpers
+    # ------------------------------------------------------------------
+
+    def is_authenticated(self) -> bool:
+        """Return ``True`` if any authentication credential is configured."""
+        return bool(
+            self.api_key or self.bearer_token or self.admin_token or self._bearer_token_factory
+        )
+
+    @staticmethod
+    def set_debug(enabled: bool = True) -> None:
+        """Enable or disable SDK debug logging."""
+        _set_debug(enabled)
+
+    @functools.cached_property
+    def with_raw_response(self) -> AsyncWithRawResponse:
+        """Return an adapter that wraps every method to return :class:`RawResponse`.
+
+        Usage::
+
+            raw = await async_client.with_raw_response.list_corpora()
+            raw.status_code   # 200
+            raw.headers       # {"content-type": "application/json", ...}
+            raw.parsed        # Page[dict] — same typed result as normal call
+        """
+        return AsyncWithRawResponse(self)
+
+
+class AsyncWithRawResponse:
+    """Adapter that wraps an :class:`AsyncKnowledge2` client so that every
+    public method returns a :class:`~sdk._raw_response.RawResponse`.
+
+    Task-safe: uses a ``contextvars.ContextVar`` so concurrent tasks
+    do not interfere with each other.
+    """
+
+    def __init__(self, client: AsyncKnowledge2) -> None:
+        self._client = client
+
+    def __getattr__(self, name: str) -> Any:
+        attr = getattr(self._client, name)
+        if not callable(attr) or name.startswith("_"):
+            raise AttributeError(name)
+
+        @functools.wraps(attr)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            token = self._client._raw_response_flag.set(True)
+            try:
+                return await attr(*args, **kwargs)
+            finally:
+                self._client._raw_response_flag.reset(token)
+
+        return wrapper