knowledge2 0.4.0__py3-none-any.whl

sdk/async_resources/corpora.py

@@ -0,0 +1,276 @@
+"""Async corpus resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._async_paging import AsyncPager
+from sdk._paging import Page
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.async_resources._mixin_base import AsyncRequesterMixin
+from sdk.errors import ConfirmationRequiredError
+from sdk.types import (
+    CorpusDeleteResponse,
+    CorpusResponse,
+    CorpusStatusResponse,
+)
+
+
+class AsyncCorporaMixin(AsyncRequesterMixin):
+    async def create_corpus(
+        self,
+        project_id: str,
+        name: str,
+        description: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> CorpusResponse:
+        """Create a new corpus within a project.
+
+        Args:
+            project_id: The project that will own the corpus.
+            name: Human-readable name for the corpus.
+            description: Optional description of the corpus contents.
+
+        Returns:
+            The newly created corpus record.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        project_id = require_str(project_id, "project_id")
+        payload: dict[str, Any] = {"project_id": project_id, "name": name}
+        if description is not None:
+            payload["description"] = description
+        data = await self._request(
+            "POST", "/v1/corpora", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "CorpusResponse")
+
+    async def list_corpora(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List corpora accessible to the current credentials.
+
+        Args:
+            limit: Maximum number of corpora to return per page.
+            offset: Number of corpora to skip for pagination.
+
+        Returns:
+            A Page containing corpus records with pagination metadata.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        return await self._list_page(
+            "GET", "/v1/corpora", items_key="corpora", limit=limit, offset=offset
+        )
+
+    def iter_corpora(
+        self,
+        *,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> AsyncPager[dict[str, Any]]:
+        """Lazily paginate corpora, yielding individual corpus items.
+
+        Args:
+            limit: Page size used for each underlying API request.
+
+        Yields:
+            Individual corpus response dicts.
+
+        Raises:
+            Knowledge2Error: If any underlying API request fails.
+        """
+        return self._paginate(
+            "GET",
+            "/v1/corpora",
+            items_key="corpora",
+            limit=limit,
+        )
+
+    async def get_corpus(
+        self,
+        corpus_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> CorpusResponse:
+        """Retrieve a single corpus by ID.
+
+        Args:
+            corpus_id: Unique identifier of the corpus.
+
+        Returns:
+            The corpus record.
+
+        Raises:
+            NotFoundError: If the corpus does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        data = await self._request(
+            "GET", f"/v1/corpora/{corpus_id}", request_options=request_options
+        )
+        return self._maybe_validate(data, "CorpusResponse")
+
+    async def get_corpus_status(
+        self,
+        corpus_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> CorpusStatusResponse:
+        """Retrieve the ingestion and indexing status of a corpus.
+
+        Args:
+            corpus_id: Unique identifier of the corpus.
+
+        Returns:
+            Status information including document counts and index state.
+
+        Raises:
+            NotFoundError: If the corpus does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        data = await self._request(
+            "GET", f"/v1/corpora/{corpus_id}/status", request_options=request_options
+        )
+        return self._maybe_validate(data, "CorpusStatusResponse")
+
+    async def update_corpus(
+        self,
+        corpus_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        chunking_config: dict[str, Any] | None = None,
+        graph_rag_policy: dict[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> CorpusResponse:
+        """Update corpus settings.
+
+        Args:
+            corpus_id: ID of the corpus to update
+            name: New name for the corpus
+            description: New description for the corpus
+            chunking_config: Default chunking configuration for documents in this corpus.
+            graph_rag_policy: Optional corpus-level GraphRAG defaults that override
+                project-level settings when present.
+
+        Returns:
+            Updated corpus response
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if chunking_config is not None:
+            payload["chunking_config"] = chunking_config
+        if graph_rag_policy is not None:
+            payload["graph_rag_policy"] = graph_rag_policy
+        data = await self._request(
+            "PATCH", f"/v1/corpora/{corpus_id}", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "CorpusResponse")
+
+    async def delete_corpus(
+        self,
+        corpus_id: str,
+        *,
+        confirm: bool = False,
+        force: bool = False,
+        request_options: RequestOptions | None = None,
+    ) -> CorpusDeleteResponse:
+        """Delete a corpus and its associated data.
+
+        This is an irreversible operation.  You must pass ``confirm=True``
+        to acknowledge this and proceed.
+
+        Args:
+            corpus_id: Unique identifier of the corpus to delete.
+            confirm: Safety guard -- must be ``True`` to execute the
+                deletion.  Raises ``ConfirmationRequiredError`` when ``False``.
+            force: If ``True``, purge dependent corpus resources during
+                deletion.
+
+        Returns:
+            Confirmation of the deletion.
+
+        Raises:
+            ConfirmationRequiredError: If *confirm* is not ``True``.
+            NotFoundError: If the corpus does not exist.
+            ConflictError: If *force* is ``False`` and the corpus has
+                active resources.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        if not confirm:
+            raise ConfirmationRequiredError("corpus", corpus_id)
+        data = await self._request(
+            "DELETE",
+            f"/v1/corpora/{corpus_id}",
+            params={"force": force},
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "CorpusDeleteResponse")
+
+    async def list_corpus_models(
+        self,
+        corpus_id: str,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List models associated with a corpus.
+
+        Args:
+            corpus_id: Unique identifier of the corpus.
+            limit: Maximum number of models to return per page.
+            offset: Number of models to skip for pagination.
+
+        Returns:
+            A Page containing model records for the corpus with pagination metadata.
+
+        Raises:
+            NotFoundError: If the corpus does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        return await self._list_page(
+            "GET",
+            f"/v1/corpora/{corpus_id}/models",
+            items_key="models",
+            limit=limit,
+            offset=offset,
+        )
+
+    def iter_corpus_models(
+        self,
+        corpus_id: str,
+        *,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> AsyncPager[dict[str, Any]]:
+        """Lazily paginate corpus models, yielding individual model items.
+
+        Args:
+            corpus_id: Unique identifier of the corpus.
+            limit: Page size used for each underlying API request.
+
+        Yields:
+            Individual model dicts.
+
+        Raises:
+            Knowledge2Error: If any underlying API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        return self._paginate(
+            "GET",
+            f"/v1/corpora/{corpus_id}/models",
+            items_key="models",
+            limit=limit,
+        )

sdk/async_resources/deployments.py

@@ -0,0 +1,106 @@
+"""Async deployment resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._async_paging import AsyncPager
+from sdk._paging import Page
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.async_resources._mixin_base import AsyncRequesterMixin
+from sdk.types import DeploymentResponse
+
+
+class AsyncDeploymentsMixin(AsyncRequesterMixin):
+    async def create_deployment(
+        self,
+        corpus_id: str,
+        model_id: str,
+        *,
+        traffic_pct: int = 100,
+        reindex: bool = True,
+        request_options: RequestOptions | None = None,
+    ) -> DeploymentResponse:
+        """Deploy a tuned model to a corpus for serving retrieval traffic.
+
+        Args:
+            corpus_id: The corpus to deploy the model to.
+            model_id: The tuned model to deploy.
+            traffic_pct: Percentage of retrieval traffic to route through
+                this deployment (0-100).
+            reindex: Whether to trigger a re-index after deployment.
+
+        Returns:
+            The created deployment record.
+
+        Raises:
+            NotFoundError: If the corpus or model does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        model_id = require_str(model_id, "model_id")
+        payload = {"model_id": model_id, "traffic_pct": traffic_pct, "reindex": reindex}
+        data = await self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/deployments",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "DeploymentResponse")
+
+    async def list_deployments(
+        self,
+        corpus_id: str,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List deployments for a corpus.
+
+        Args:
+            corpus_id: The corpus whose deployments to list.
+            limit: Maximum number of deployments to return per page.
+            offset: Number of deployments to skip for pagination.
+
+        Returns:
+            A Page containing deployment records with pagination metadata.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        return await self._list_page(
+            "GET",
+            f"/v1/corpora/{corpus_id}/deployments",
+            items_key="items",
+            limit=limit,
+            offset=offset,
+        )
+
+    def iter_deployments(
+        self,
+        corpus_id: str,
+        *,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> AsyncPager[dict[str, Any]]:
+        """Iterate over deployments, automatically paginating.
+
+        Args:
+            corpus_id: The corpus whose deployments to iterate.
+            limit: Page size used for each underlying API request.
+
+        Yields:
+            Individual deployment dicts.
+
+        Raises:
+            Knowledge2Error: If any underlying API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        return self._paginate(
+            "GET",
+            f"/v1/corpora/{corpus_id}/deployments",
+            items_key="items",
+            limit=limit,
+        )