knowledge2 0.4.0__py3-none-any.whl

sdk/async_resources/usage.py

@@ -0,0 +1,91 @@
+"""Async usage metrics resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._request_options import RequestOptions
+from sdk.async_resources._mixin_base import AsyncRequesterMixin
+from sdk.types import UsageByCorpusResponse, UsageByKeyResponse, UsageSummaryResponse
+
+
+class AsyncUsageMixin(AsyncRequesterMixin):
+    async def usage_summary(
+        self,
+        *,
+        range_value: str = "7d",
+        corpus_id: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> UsageSummaryResponse:
+        """Retrieve an aggregate usage summary.
+
+        .. note:: Requires **bearer token** auth, not an API key.
+
+        Args:
+            range_value: Time range for the summary (e.g. ``"7d"``,
+                ``"30d"``).
+            corpus_id: Optional corpus to scope the summary to.
+
+        Returns:
+            Aggregated usage statistics for the requested period.
+
+        Raises:
+            AuthenticationError: If called with an API key instead of a
+                bearer token.
+            Knowledge2Error: If the API request fails.
+        """
+        params: dict[str, Any] = {"range": range_value}
+        if corpus_id:
+            params["corpus_id"] = corpus_id
+        data = await self._request(
+            "GET", "/v1/usage/summary", params=params, request_options=request_options
+        )
+        return self._maybe_validate(data, "UsageSummaryResponse")
+
+    async def usage_by_corpus(
+        self,
+        *,
+        range_value: str = "7d",
+        request_options: RequestOptions | None = None,
+    ) -> UsageByCorpusResponse:
+        """Retrieve usage metrics broken down by corpus.
+
+        .. note:: Requires **bearer token** auth, not an API key.
+
+        Args:
+            range_value: Time range for the breakdown (e.g. ``"7d"``,
+                ``"30d"``).
+
+        Returns:
+            Per-corpus usage statistics for the requested period.
+
+        Raises:
+            AuthenticationError: If called with an API key instead of a
+                bearer token.
+            Knowledge2Error: If the API request fails.
+        """
+        data = await self._request(
+            "GET",
+            "/v1/usage/by_corpus",
+            params={"range": range_value},
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "UsageByCorpusResponse")
+
+    async def usage_by_key(
+        self, *, request_options: RequestOptions | None = None
+    ) -> UsageByKeyResponse:
+        """Retrieve usage metrics broken down by API key.
+
+        .. note:: Requires **bearer token** auth, not an API key.
+
+        Returns:
+            Per-key usage statistics.
+
+        Raises:
+            AuthenticationError: If called with an API key instead of a
+                bearer token.
+            Knowledge2Error: If the API request fails.
+        """
+        data = await self._request("GET", "/v1/usage/by_key", request_options=request_options)
+        return self._maybe_validate(data, "UsageByKeyResponse")

sdk/client.py

@@ -0,0 +1,417 @@
+"""Knowledge2 API client.
+
+Usage::
+
+    from sdk import Knowledge2
+
+    client = Knowledge2(api_key="k2_...")
+    results = client.search(corpus_id, "my query")
+
+    # With validated config object:
+    from sdk import K2Config
+    config = K2Config(api_key="k2_...", max_retries=5)
+    client = Knowledge2(config=config)
+
+    # From environment variables:
+    client = Knowledge2.from_env()
+"""
+
+from __future__ import annotations
+
+import functools
+import threading
+from collections.abc import Callable
+from functools import cached_property
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from sdk._base import BaseClient, ClientLimits, ClientTimeouts
+from sdk._logging import set_debug as _set_debug
+from sdk.resources import (
+    A2AMixin,
+    AgentsMixin,
+    AuditMixin,
+    AuthMixin,
+    ConsoleMixin,
+    CorporaMixin,
+    DeploymentsMixin,
+    DocumentsMixin,
+    FeedsMixin,
+    IndexesMixin,
+    JobsMixin,
+    MetadataMixin,
+    ModelsMixin,
+    OnboardingMixin,
+    OrgsMixin,
+    PipelinesMixin,
+    ProjectsMixin,
+    SearchMixin,
+    TrainingMixin,
+    UsageMixin,
+)
+
+if TYPE_CHECKING:
+    from sdk.config import K2Config
+    from sdk.namespaces import (
+        AuthNamespace,
+        CorporaNamespace,
+        DeploymentsNamespace,
+        DocumentsNamespace,
+        JobsNamespace,
+        ModelsNamespace,
+        SearchNamespace,
+        TrainingNamespace,
+    )
+
+DEFAULT_API_HOST = "https://api.knowledge2.ai"
+
+_SENTINEL = object()
+
+
+class Knowledge2(
+    BaseClient,
+    OrgsMixin,
+    AuthMixin,
+    ProjectsMixin,
+    CorporaMixin,
+    ModelsMixin,
+    DocumentsMixin,
+    IndexesMixin,
+    SearchMixin,
+    MetadataMixin,
+    TrainingMixin,
+    DeploymentsMixin,
+    JobsMixin,
+    AuditMixin,
+    UsageMixin,
+    ConsoleMixin,
+    OnboardingMixin,
+    AgentsMixin,
+    FeedsMixin,
+    PipelinesMixin,
+    A2AMixin,
+):
+    """Knowledge2 API client.
+
+    The SDK is intentionally self-contained so it can be published directly from
+    the ``sdk/`` directory.
+
+    Args:
+        config: Optional :class:`~sdk.config.K2Config` instance.  When
+            provided, its values are used as defaults that can be
+            overridden by explicit keyword arguments.
+        api_host: Base URL of the Knowledge2 API.
+        api_key: API key for authentication (``X-API-Key`` header).
+        org_id: Organisation ID.  Auto-detected from the API key when
+            omitted via a ``GET /v1/auth/whoami`` call during construction.
+            Pass explicitly to skip this network call.
+        bearer_token: Bearer token for console / Auth0 authentication.
+        bearer_token_factory: Callable returning a bearer token string.
+            Called lazily on first request and cached for
+            ``token_cache_ttl`` seconds.  Mutually exclusive with
+            ``bearer_token``.
+        token_cache_ttl: Seconds to cache the factory-produced token
+            (default 300).  Set to ``0`` to disable caching.
+        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 for transient
+            errors (5xx, 429, connection failures, timeouts).  Set to
+            ``0`` to disable.
+        http_client: Pre-configured ``httpx.Client`` to use for HTTP
+            transport.  When supplied, the SDK does **not** close it —
+            the caller retains ownership.  ``timeout`` and ``limits``
+            are ignored (configure them on the client directly).
+        lazy: When ``True``, skip the automatic ``GET /v1/auth/whoami``
+            call during construction.  ``org_id`` will remain ``None``
+            unless provided explicitly or resolved later via
+            :meth:`get_whoami`.  Defaults to ``False``.
+    """
+
+    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.Client | None = None,
+        lazy: bool = False,
+    ) -> 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
+        if not lazy and self.org_id is None and resolved_api_key is not None:
+            whoami = self.get_whoami()
+            self.org_id = whoami["org_id"] if isinstance(whoami, dict) else whoami.org_id  # type: ignore[attr-defined]
+
+    # ------------------------------------------------------------------
+    # Factory classmethods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> Knowledge2:
+        """Create a client from ``K2_*`` environment variables.
+
+        Equivalent to ``Knowledge2(config=K2Config())``, with any
+        *overrides* passed as constructor kwargs.
+
+        Requires ``pydantic-settings`` — install via
+        ``pip install knowledge2[config]``.
+        """
+        from sdk.config import K2Config
+
+        config = K2Config()
+        return cls(config=config, **overrides)
+
+    @classmethod
+    def from_file(cls, path: str | Path, **overrides: Any) -> Knowledge2:
+        """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 (e.g. ``api_key="k2_..."``).
+        """
+        from sdk.config import K2Config
+
+        config = K2Config.from_file(path, **overrides)
+        return cls(config=config)
+
+    @classmethod
+    def from_profile(
+        cls,
+        name: str,
+        path: str | Path | None = None,
+        **overrides: Any,
+    ) -> Knowledge2:
+        """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 (e.g. ``api_key="k2_..."``).
+        """
+        from sdk.config import K2Config
+
+        config = K2Config.from_profile(name, path=path, **overrides)
+        return cls(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.
+
+        When enabled, request method, URL, response status, and retry
+        attempts are logged to stderr.  Authentication headers are
+        redacted.
+
+        Args:
+            enabled: ``True`` to turn on debug logging, ``False`` to
+                turn it off.
+        """
+        _set_debug(enabled)
+
+    # ------------------------------------------------------------------
+    # Namespace accessors
+    # ------------------------------------------------------------------
+
+    @cached_property
+    def with_raw_response(self) -> WithRawResponse:
+        """Return an adapter that wraps every method to return :class:`RawResponse`.
+
+        Usage::
+
+            raw = 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 WithRawResponse(self)
+
+    @cached_property
+    def documents(self) -> DocumentsNamespace:
+        """Document operations namespace: ``client.documents.*``"""
+        from sdk.namespaces import DocumentsNamespace
+
+        return DocumentsNamespace(self)
+
+    @cached_property
+    def corpora(self) -> CorporaNamespace:
+        """Corpus operations namespace: ``client.corpora.*``"""
+        from sdk.namespaces import CorporaNamespace
+
+        return CorporaNamespace(self)
+
+    @cached_property
+    def search_ns(self) -> SearchNamespace:
+        """Search operations namespace: ``client.search_ns.*``
+
+        Named ``search_ns`` to avoid shadowing the :meth:`search` method.
+        """
+        from sdk.namespaces import SearchNamespace
+
+        return SearchNamespace(self)
+
+    @cached_property
+    def models_ns(self) -> ModelsNamespace:
+        """Model operations namespace: ``client.models_ns.*``
+
+        Named ``models_ns`` to avoid shadowing the ``models`` attribute
+        used by some serialization libraries.
+        """
+        from sdk.namespaces import ModelsNamespace
+
+        return ModelsNamespace(self)
+
+    @cached_property
+    def jobs(self) -> JobsNamespace:
+        """Job operations namespace: ``client.jobs.*``"""
+        from sdk.namespaces import JobsNamespace
+
+        return JobsNamespace(self)
+
+    @cached_property
+    def training_ns(self) -> TrainingNamespace:
+        """Training operations namespace: ``client.training_ns.*``"""
+        from sdk.namespaces import TrainingNamespace
+
+        return TrainingNamespace(self)
+
+    @cached_property
+    def deployments(self) -> DeploymentsNamespace:
+        """Deployment operations namespace: ``client.deployments.*``"""
+        from sdk.namespaces import DeploymentsNamespace
+
+        return DeploymentsNamespace(self)
+
+    @cached_property
+    def auth(self) -> AuthNamespace:
+        """Auth operations namespace: ``client.auth.*``"""
+        from sdk.namespaces import AuthNamespace
+
+        return AuthNamespace(self)
+
+
+class WithRawResponse:
+    """Adapter that wraps a :class:`Knowledge2` client so that every
+    public method returns a :class:`~sdk._raw_response.RawResponse`
+    exposing HTTP status code, headers, and the parsed body.
+
+    Thread-safe: uses a ``threading.local`` flag so concurrent threads
+    do not interfere with each other.
+    """
+
+    def __init__(self, client: Knowledge2) -> 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)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            self._client._raw_response_flag.enabled = True
+            try:
+                return attr(*args, **kwargs)
+            finally:
+                self._client._raw_response_flag.enabled = False
+
+        return wrapper
+
+
+class Knowledge2Validated(Knowledge2):
+    """Knowledge2 client with Pydantic response validation enabled by default.
+
+    Equivalent to ``Knowledge2(validate_responses=True)``.
+    Requires: ``pip install knowledge2[pydantic]``
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs.setdefault("validate_responses", True)
+        super().__init__(**kwargs)

sdk/config.py

@@ -0,0 +1,182 @@
+"""Typed, validated, immutable configuration for the Knowledge2 SDK.
+
+Requires the ``pydantic-settings`` package::
+
+    pip install knowledge2[config]
+
+Usage::
+
+    from sdk import Knowledge2, K2Config
+
+    # From environment variables (K2_API_KEY, K2_API_HOST, etc.)
+    config = K2Config()
+    client = Knowledge2(config=config)
+
+    # Explicit values — invalid config raises at construction
+    config = K2Config(api_key="k2_...", max_retries=5)
+    client = Knowledge2(config=config)
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+    from pydantic import Field, PositiveFloat, PositiveInt
+    from pydantic_settings import BaseSettings, SettingsConfigDict
+except ImportError as _exc:
+    raise ImportError(
+        "K2Config requires 'pydantic-settings'. Install it with: pip install knowledge2[config]"
+    ) from _exc
+
+
+class K2Config(BaseSettings):
+    """Frozen, validated configuration for :class:`~sdk.client.Knowledge2`.
+
+    Populated from environment variables with the ``K2_`` prefix
+    (e.g. ``K2_API_KEY``, ``K2_API_HOST``), or passed directly.
+
+    Invalid values (negative timeouts, unknown keys) raise a
+    :class:`pydantic.ValidationError` at construction time — not at
+    first request.
+
+    The object is **frozen** after creation; mutating fields raises an
+    error.
+    """
+
+    api_host: str = Field(default="https://api.knowledge2.ai")
+    api_key: str | None = Field(default=None, repr=False)
+    org_id: str | None = Field(default=None)
+    bearer_token: str | None = Field(default=None, repr=False)
+    admin_token: str | None = Field(default=None, repr=False)
+    max_retries: PositiveInt = Field(default=2)
+    timeout_connect: PositiveFloat | None = Field(default=5.0)
+    timeout_read: PositiveFloat | None = Field(default=60.0)
+    timeout_write: PositiveFloat | None = Field(default=30.0)
+    max_connections: PositiveInt = Field(default=20)
+    max_keepalive_connections: PositiveInt = Field(default=10)
+
+    model_config = SettingsConfigDict(
+        env_prefix="K2_",
+        frozen=True,
+        extra="forbid",
+    )
+
+    @classmethod
+    def from_file(cls, path: str | Path, **overrides: Any) -> K2Config:
+        """Load configuration from a JSON or YAML file.
+
+        YAML support requires ``PyYAML`` (install via
+        ``pip install knowledge2[yaml]``).
+
+        Explicit *overrides* take precedence over file values.
+
+        Args:
+            path: Path to a JSON or YAML configuration file.
+            **overrides: K2Config field values that override the file
+                contents (e.g. ``api_key="k2_..."``).  Only config
+                field names are accepted.
+
+        Returns:
+            A frozen :class:`K2Config` instance.
+        """
+        p = Path(path).expanduser()
+        raw = p.read_text(encoding="utf-8")
+
+        suffix = p.suffix.lower()
+        if suffix in {".yaml", ".yml"}:
+            try:
+                import yaml  # type: ignore[import-untyped]
+            except ImportError as exc:
+                raise ImportError(
+                    "YAML config requires 'PyYAML'. Install it with: pip install knowledge2[yaml]"
+                ) from exc
+            data: dict[str, Any] = yaml.safe_load(raw) or {}
+        else:
+            data = json.loads(raw)
+
+        if not isinstance(data, dict):
+            raise TypeError(
+                f"Config file must contain a JSON/YAML mapping, got {type(data).__name__}"
+            )
+        data.update(overrides)
+        return cls(**data)
+
+    @classmethod
+    def from_profile(
+        cls,
+        name: str,
+        path: str | Path | None = None,
+        **overrides: Any,
+    ) -> K2Config:
+        """Load a named profile from a multi-profile config file.
+
+        The file must contain a top-level mapping where each key is a
+        profile name and each value is a config dict::
+
+            # ~/.k2/config.yaml
+            default:
+              api_key: k2_prod_...
+            staging:
+              api_host: https://staging.api.knowledge2.ai
+              api_key: k2_stg_...
+
+        Args:
+            name: The profile key to load.
+            path: Config file path.  Defaults to ``~/.k2/config.yaml``
+                (falls back to ``~/.k2/config.json``).
+            **overrides: K2Config field values that override the
+                profile contents.  Only config field names are accepted.
+
+        Returns:
+            A frozen :class:`K2Config` instance.
+
+        Raises:
+            FileNotFoundError: If no config file is found.
+            KeyError: If the profile name is not in the file.
+        """
+        if path is not None:
+            resolved = Path(path).expanduser()
+        else:
+            base = Path.home() / ".k2"
+            yaml_path = base / "config.yaml"
+            yml_path = base / "config.yml"
+            json_path = base / "config.json"
+            if yaml_path.exists():
+                resolved = yaml_path
+            elif yml_path.exists():
+                resolved = yml_path
+            elif json_path.exists():
+                resolved = json_path
+            else:
+                raise FileNotFoundError(
+                    f"No config file found at {yaml_path}, {yml_path}, or {json_path}"
+                )
+
+        raw = resolved.read_text(encoding="utf-8")
+        suffix = resolved.suffix.lower()
+        if suffix in {".yaml", ".yml"}:
+            try:
+                import yaml
+            except ImportError as exc:
+                raise ImportError(
+                    "YAML config requires 'PyYAML'. Install it with: pip install knowledge2[yaml]"
+                ) from exc
+            all_profiles: dict[str, Any] = yaml.safe_load(raw) or {}
+        else:
+            all_profiles = json.loads(raw)
+
+        if not isinstance(all_profiles, dict):
+            raise TypeError(
+                f"Config file must contain a mapping of profiles, got {type(all_profiles).__name__}"
+            )
+        if name not in all_profiles:
+            raise KeyError(
+                f"Profile '{name}' not found. Available profiles: {', '.join(all_profiles.keys())}"
+            )
+
+        data = dict(all_profiles[name])
+        data.update(overrides)
+        return cls(**data)