knowledge2 0.4.0__py3-none-any.whl

sdk/resources/feeds.py

@@ -0,0 +1,246 @@
+"""Feed resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._paging import Page
+from sdk._preview import preview_resource
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.resources._mixin_base import RequesterMixin
+
+
+@preview_resource
+class FeedsMixin(RequesterMixin):
+    def create_feed(
+        self,
+        *,
+        project_id: str,
+        name: str,
+        query: str = "",
+        persistent: bool = False,
+        target_corpus: dict[str, Any] | None = None,
+        reactive: bool = False,
+        agent_id: str | None = None,
+        schedule_interval: str | None = None,
+        schedule_hour: int | None = None,
+        start_from: str | None = None,
+        top_k: int | None = None,
+        metadata_filters: dict[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Create a new knowledge feed.
+
+        Args:
+            project_id: ID of the project that will own the feed.
+            name: Human-readable name for the feed.
+            query: Query string for the feed (defaults to empty string).
+            persistent: Whether the feed persists results to storage.
+            target_corpus: Optional target corpus configuration dict. Pass
+                ``{"existing": "<corpus-id>"}`` to write into an existing corpus,
+                or ``{"create_new": True}`` to have the API create a new one.
+            reactive: Whether the feed triggers on new data automatically.
+            agent_id: Optional agent ID to associate with the feed.
+            schedule_interval: Optional cron-style schedule interval.
+            schedule_hour: UTC hour (0-23) for daily scheduled feeds. Only
+                valid when schedule_interval is ``'1d'``.
+            start_from: Optional ISO-8601 timestamp to start processing from.
+            top_k: Optional number of top results to return per run.
+            metadata_filters: Optional metadata filter dictionary.
+
+        Returns:
+            The newly created feed 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,
+            "query": query,
+            "persistent": persistent,
+            "reactive": reactive,
+        }
+        if target_corpus is not None:
+            payload["target_corpus"] = target_corpus
+        if agent_id is not None:
+            payload["agent_id"] = agent_id
+        if schedule_interval is not None:
+            payload["schedule_interval"] = schedule_interval
+        if schedule_hour is not None:
+            payload["schedule_hour"] = schedule_hour
+        if start_from is not None:
+            payload["start_from"] = start_from
+        if top_k is not None:
+            payload["top_k"] = top_k
+        if metadata_filters is not None:
+            payload["metadata_filters"] = metadata_filters
+        data = self._request("POST", "/v1/feeds", json=payload, request_options=request_options)
+        return self._maybe_validate(data, "FeedResponse")
+
+    def list_feeds(
+        self,
+        *,
+        project_id: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List feeds accessible to the current credentials.
+
+        Args:
+            project_id: Optional project ID to filter feeds by.
+            limit: Maximum number of feeds to return per page.
+            offset: Number of feeds to skip for pagination.
+
+        Returns:
+            A Page containing feed records with pagination metadata.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        params: dict[str, Any] = {}
+        if project_id is not None:
+            params["project_id"] = project_id
+        return self._list_page(
+            "GET",
+            "/v1/feeds",
+            items_key="feeds",
+            params=params or None,
+            limit=limit,
+            offset=offset,
+        )
+
+    def get_feed(
+        self,
+        feed_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Retrieve a single feed by ID.
+
+        Args:
+            feed_id: Unique identifier of the feed.
+
+        Returns:
+            The feed record.
+
+        Raises:
+            NotFoundError: If the feed does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        feed_id = require_str(feed_id, "feed_id")
+        data = self._request("GET", f"/v1/feeds/{feed_id}", request_options=request_options)
+        return self._maybe_validate(data, "FeedResponse")
+
+    def update_feed(
+        self,
+        feed_id: str,
+        *,
+        name: str | None = None,
+        query: str | None = None,
+        top_k: int | None = None,
+        metadata_filters: dict[str, Any] | None = None,
+        reactive: bool | None = None,
+        schedule_interval: str | None = None,
+        schedule_hour: int | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Update feed settings.
+
+        Args:
+            feed_id: ID of the feed to update.
+            name: New name for the feed.
+            query: New query string for the feed.
+            top_k: New number of top results to return per run.
+            metadata_filters: New metadata filter dictionary.
+            reactive: Whether the feed triggers on new data automatically.
+            schedule_interval: New cron-style schedule interval.
+            schedule_hour: UTC hour (0-23) for daily scheduled feeds. Only
+                valid when schedule_interval is ``'1d'``.
+
+        Returns:
+            Updated feed record.
+
+        Raises:
+            NotFoundError: If the feed does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        feed_id = require_str(feed_id, "feed_id")
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if query is not None:
+            payload["query"] = query
+        if top_k is not None:
+            payload["top_k"] = top_k
+        if metadata_filters is not None:
+            payload["metadata_filters"] = metadata_filters
+        if reactive is not None:
+            payload["reactive"] = reactive
+        if schedule_interval is not None:
+            payload["schedule_interval"] = schedule_interval
+        if schedule_hour is not None:
+            payload["schedule_hour"] = schedule_hour
+        data = self._request(
+            "PATCH", f"/v1/feeds/{feed_id}", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "FeedResponse")
+
+    def delete_feed(
+        self,
+        feed_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> None:
+        """Delete a feed.
+
+        Args:
+            feed_id: Unique identifier of the feed to delete.
+
+        Returns:
+            None (the API returns 204 No Content on success).
+
+        Raises:
+            NotFoundError: If the feed does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        feed_id = require_str(feed_id, "feed_id")
+        self._request("DELETE", f"/v1/feeds/{feed_id}", request_options=request_options)
+
+    def run_feed(
+        self,
+        feed_id: str,
+        *,
+        return_results: bool | None = None,
+        dry_run: bool = False,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Trigger a feed run.
+
+        Args:
+            feed_id: Unique identifier of the feed to run.
+            return_results: Whether to include results in the response.
+                When ``None`` (default), the API applies a smart default
+                based on feed type (``True`` for standard, ``False`` for
+                persistent feeds).
+            dry_run: If ``True``, simulate the run without persisting results.
+
+        Returns:
+            A dict containing the feed run results and metadata.
+
+        Raises:
+            NotFoundError: If the feed does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        feed_id = require_str(feed_id, "feed_id")
+        params: dict[str, Any] = {"dry_run": dry_run}
+        if return_results is not None:
+            params["return_results"] = return_results
+        data = self._request(
+            "POST",
+            f"/v1/feeds/{feed_id}/run",
+            params=params,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "FeedRunResponse")

sdk/resources/indexes.py

@@ -0,0 +1,210 @@
+"""Index management resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.resources._mixin_base import RequesterMixin
+from sdk.types import IndexBuildResponse, IndexCompactResponse, IndexStatusResponse
+
+
+class IndexesMixin(RequesterMixin):
+    def sync_indexes(
+        self,
+        corpus_id: str,
+        *,
+        wait: bool = True,
+        poll_s: int = 5,
+        idempotency_key: str | None = None,
+    ) -> IndexBuildResponse:
+        """Synchronize the default core retrieval indexes for a corpus.
+
+        This is the simplest public indexing entrypoint. It queues the platform's
+        synchronized core retrieval snapshot using the default automatic
+        incremental behavior and does not request GraphRAG artifacts.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        headers = self._idempotency_headers(idempotency_key)
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/indexes:sync",
+            headers=headers,
+        )
+        if wait:
+            job_id = data.get("job_id")
+            if job_id:
+                self._wait_for_job(job_id, poll_s=poll_s)
+        return cast("IndexBuildResponse", data)
+
+    def build_indexes(
+        self,
+        corpus_id: str,
+        dense: bool = True,
+        sparse: bool = True,
+        sparse_metadata: bool | None = None,
+        mode: str = "incremental",
+        idempotency_key: str | None = None,
+        *,
+        sparse_metadata_required: bool = False,
+        wait: bool = True,
+        poll_s: int = 5,
+        request_options: RequestOptions | None = None,
+    ) -> IndexBuildResponse:
+        """Advanced index build entrypoint for a corpus.
+
+        Args:
+            corpus_id: The corpus to build indexes for.
+            dense: Whether to build a dense (vector) index.
+            sparse: Whether to build a sparse (BM25) index.
+            sparse_metadata: Whether to build the metadata sparse (BM25)
+                index. ``None`` uses the server default.
+            sparse_metadata_required: Whether metadata sparse is required for
+                successful completion. When ``True``, a metadata-sparse skip is
+                treated as a build failure.
+            mode: Build mode — ``"incremental"`` is the default synchronized
+                snapshot path, while ``"full"`` forces a rebuild from scratch.
+            idempotency_key: Optional idempotency key to prevent
+                duplicate builds.
+            wait: If ``True`` (default), block until the index build
+                job completes.
+            poll_s: Polling interval in seconds when *wait* is ``True``.
+
+        For most callers, :meth:`sync_indexes` is the simpler default.
+
+        Returns:
+            The index build response, including the background job ID.
+
+        Raises:
+            NotFoundError: If the corpus does not exist.
+            ConflictError: If a duplicate idempotency key is detected.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        payload = {"dense": dense, "sparse": sparse, "mode": mode}
+        if sparse_metadata is not None:
+            payload["sparse_metadata"] = bool(sparse_metadata)
+        if sparse_metadata_required:
+            payload["sparse_metadata_required"] = True
+        headers = self._idempotency_headers(idempotency_key)
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/indexes:build",
+            json=payload,
+            headers=headers,
+            request_options=request_options,
+        )
+        if wait:
+            job_id = data.get("job_id")
+            if job_id:
+                self._wait_for_job(job_id, poll_s=poll_s)
+        return self._maybe_validate(data, "IndexBuildResponse")
+
+    def index_status(
+        self,
+        corpus_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> IndexStatusResponse:
+        """Retrieve the current index status for a corpus.
+
+        Args:
+            corpus_id: The corpus to check.
+
+        Returns:
+            Index status including a top-level retrieval summary plus per-family details.
+
+        Raises:
+            NotFoundError: If the corpus does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        data = self._request(
+            "GET", f"/v1/corpora/{corpus_id}/indexes/status", request_options=request_options
+        )
+        return self._maybe_validate(data, "IndexStatusResponse")
+
+    def rebuild_indexes(
+        self,
+        corpus_id: str,
+        dense: bool = True,
+        sparse: bool = True,
+        sparse_metadata: bool | None = None,
+        idempotency_key: str | None = None,
+        *,
+        sparse_metadata_required: bool = False,
+        request_options: RequestOptions | None = None,
+    ) -> IndexBuildResponse:
+        """Force a full rebuild of indexes for a corpus.
+
+        Unlike :meth:`build_indexes`, this always performs a full rebuild
+        regardless of existing index state.
+
+        Args:
+            corpus_id: The corpus to rebuild indexes for.
+            dense: Whether to rebuild the dense (vector) index.
+            sparse: Whether to rebuild the sparse (BM25) index.
+            sparse_metadata: Whether to rebuild the metadata sparse
+                (BM25) index. ``None`` uses the server default.
+            sparse_metadata_required: Whether metadata sparse is required for
+                successful completion. When ``True``, a metadata-sparse skip is
+                treated as a build failure.
+            idempotency_key: Optional idempotency key to prevent
+                duplicate rebuilds.
+
+        Returns:
+            The index build response, including the background job ID.
+
+        Raises:
+            NotFoundError: If the corpus does not exist.
+            ConflictError: If a duplicate idempotency key is detected.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        payload = {"dense": dense, "sparse": sparse, "mode": "full"}
+        if sparse_metadata is not None:
+            payload["sparse_metadata"] = bool(sparse_metadata)
+        if sparse_metadata_required:
+            payload["sparse_metadata_required"] = True
+        headers = self._idempotency_headers(idempotency_key)
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/indexes:rebuild",
+            json=payload,
+            headers=headers,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "IndexBuildResponse")
+
+    def compact_indexes(
+        self,
+        corpus_id: str,
+        *,
+        dense: bool = True,
+        sparse: bool = True,
+        keep: int = 1,
+        request_options: RequestOptions | None = None,
+    ) -> IndexCompactResponse:
+        """Compact index artifacts for a corpus, removing old generations.
+
+        Args:
+            corpus_id: The corpus whose indexes to compact.
+            dense: Whether to compact dense index artifacts.
+            sparse: Whether to compact sparse index artifacts.
+            keep: Number of recent index generations to retain.
+
+        Returns:
+            A summary of compacted artifacts.
+
+        Raises:
+            NotFoundError: If the corpus does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/indexes:compact",
+            params={"dense": dense, "sparse": sparse, "keep": keep},
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "IndexCompactResponse")

sdk/resources/jobs.py

@@ -0,0 +1,164 @@
+"""Job management resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._paging import Page, SyncPager
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.resources._mixin_base import RequesterMixin
+from sdk.types import JobResponse, JobStatusResponse, ReconcileJobsResponse
+
+
+class JobsMixin(RequesterMixin):
+    def get_job(
+        self,
+        job_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> JobResponse:
+        """Retrieve details of a single job.
+
+        Args:
+            job_id: Unique identifier of the job.
+
+        Returns:
+            The job record including type, status, and metadata.
+
+        Raises:
+            NotFoundError: If the job does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        job_id = require_str(job_id, "job_id")
+        data = self._request("GET", f"/v1/jobs/{job_id}", request_options=request_options)
+        return self._maybe_validate(data, "JobResponse")
+
+    def list_jobs(
+        self,
+        *,
+        corpus_id: str | None = None,
+        job_type: str | None = None,
+        status: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List jobs with optional filters.
+
+        Args:
+            corpus_id: Filter to jobs belonging to this corpus.
+            job_type: Filter by job type (e.g. ``"ingest"``, ``"index"``,
+                ``"train"``).
+            status: Filter by job status (e.g. ``"pending"``,
+                ``"running"``, ``"completed"``, ``"failed"``).
+            limit: Maximum number of jobs to return per page.
+            offset: Number of jobs to skip for pagination.
+
+        Returns:
+            A Page containing job records with pagination metadata.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        params: dict[str, Any] = {}
+        if corpus_id:
+            params["corpus_id"] = corpus_id
+        if job_type:
+            params["job_type"] = job_type
+        if status:
+            params["status"] = status
+        return self._list_page(
+            "GET", "/v1/jobs", items_key="jobs", params=params or None, limit=limit, offset=offset
+        )
+
+    def iter_jobs(
+        self,
+        *,
+        corpus_id: str | None = None,
+        job_type: str | None = None,
+        status: str | None = None,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> SyncPager[dict[str, Any]]:
+        """Iterate over jobs, automatically paginating.
+
+        Args:
+            corpus_id: Filter to jobs belonging to this corpus.
+            job_type: Filter by job type.
+            status: Filter by job status.
+            limit: Page size used for each underlying API request.
+
+        Yields:
+            Individual job dicts.
+
+        Raises:
+            Knowledge2Error: If any underlying API request fails.
+        """
+        params: dict[str, Any] = {}
+        if corpus_id:
+            params["corpus_id"] = corpus_id
+        if job_type:
+            params["job_type"] = job_type
+        if status:
+            params["status"] = status
+        return self._paginate(
+            "GET", "/v1/jobs", items_key="jobs", params=params or None, limit=limit
+        )
+
+    def cancel_job(
+        self,
+        job_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> JobStatusResponse:
+        """Cancel a running or pending job.
+
+        Args:
+            job_id: Unique identifier of the job to cancel.
+
+        Returns:
+            The updated job status after cancellation.
+
+        Raises:
+            NotFoundError: If the job does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        job_id = require_str(job_id, "job_id")
+        data = self._request("POST", f"/v1/jobs/{job_id}:cancel", request_options=request_options)
+        return self._maybe_validate(data, "JobStatusResponse")
+
+    def retry_job(
+        self,
+        job_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> JobStatusResponse:
+        """Retry a failed job.
+
+        Args:
+            job_id: Unique identifier of the job to retry.
+
+        Returns:
+            The updated job status after scheduling the retry.
+
+        Raises:
+            NotFoundError: If the job does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        job_id = require_str(job_id, "job_id")
+        data = self._request("POST", f"/v1/jobs/{job_id}:retry", request_options=request_options)
+        return self._maybe_validate(data, "JobStatusResponse")
+
+    def reconcile_jobs(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> ReconcileJobsResponse:
+        """Reconcile stale or stuck jobs across the platform.
+
+        Returns:
+            A summary of reconciled jobs (e.g. counts of requeued or
+            cancelled jobs).
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("POST", "/v1/jobs:reconcile", request_options=request_options)
+        return self._maybe_validate(data, "ReconcileJobsResponse")

sdk/resources/metadata.py

@@ -0,0 +1,53 @@
+"""Metadata discovery resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.resources._mixin_base import RequesterMixin
+
+
+class MetadataMixin(RequesterMixin):
+    """Metadata discovery operations."""
+
+    def discover_metadata(
+        self,
+        corpus_id: str,
+        *,
+        refresh: bool = False,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Discover metadata fields available in a corpus.
+
+        Returns distinct metadata keys with inferred types, value
+        distributions, and basic statistics.
+
+        Args:
+            corpus_id: Corpus ID to discover metadata for.
+            refresh: Force cache refresh (bypass cached results).
+
+        Returns:
+            Discovery response with fields, types, and stats.
+
+        Raises:
+            NotFoundError: If the corpus does not exist.
+            Knowledge2Error: If the API request fails.
+
+        Example:
+            >>> info = client.discover_metadata("corpus-123")
+            >>> for field in info["fields"]:
+            ...     print(field["key"], field["type"], field["count"])
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        params: dict[str, Any] = {}
+        if refresh:
+            params["refresh"] = "true"
+        data = self._request(
+            "GET",
+            f"/v1/corpora/{corpus_id}/metadata/discover",
+            params=params,
+            request_options=request_options,
+        )
+        return data