knowledge2 0.4.0__py3-none-any.whl

sdk/resources/pipelines.py

@@ -0,0 +1,520 @@
+"""Pipeline Spec resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._paging import Page, SyncPager
+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 PipelinesMixin(RequesterMixin):
+    # ------------------------------------------------------------------
+    # CRUD
+    # ------------------------------------------------------------------
+
+    def create_pipeline_spec(
+        self,
+        *,
+        project_id: str,
+        name: str,
+        topology: dict[str, Any],
+        description: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Create a new pipeline spec.
+
+        Args:
+            project_id: ID of the project that will own the pipeline spec.
+            name: Human-readable name for the pipeline spec.
+            topology: Topology document describing corpora, agents, feeds,
+                and subscriptions.
+            description: Optional description of the pipeline spec.
+
+        Returns:
+            The newly created pipeline spec record.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        project_id = require_str(project_id, "project_id")
+        name = require_str(name, "name")
+        payload: dict[str, Any] = {
+            "project_id": project_id,
+            "name": name,
+            "topology": topology,
+        }
+        if description is not None:
+            payload["description"] = description
+        data = self._request(
+            "POST", "/v1/pipeline-specs", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "PipelineSpecResponse")
+
+    def get_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Retrieve a single pipeline spec by ID.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The pipeline spec record.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "GET",
+            f"/v1/pipeline-specs/{pipeline_spec_id}",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "PipelineSpecResponse")
+
+    def list_pipeline_specs(
+        self,
+        *,
+        project_id: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List pipeline specs accessible to the current credentials.
+
+        Args:
+            project_id: Optional project ID to filter by.
+            limit: Maximum number of pipeline specs to return per page.
+            offset: Number of pipeline specs to skip for pagination.
+
+        Returns:
+            A Page containing pipeline spec 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/pipeline-specs",
+            items_key="pipeline_specs",
+            params=params or None,
+            limit=limit,
+            offset=offset,
+        )
+
+    def iter_pipeline_specs(
+        self,
+        *,
+        project_id: str | None = None,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> SyncPager[dict[str, Any]]:
+        """Lazily paginate pipeline specs, yielding individual items.
+
+        Args:
+            project_id: Optional project ID to filter by.
+            limit: Page size used for each underlying API request.
+
+        Yields:
+            Individual pipeline spec response dicts.
+
+        Raises:
+            Knowledge2Error: If any underlying API request fails.
+        """
+        params: dict[str, Any] = {}
+        if project_id is not None:
+            params["project_id"] = project_id
+        return self._paginate(
+            "GET",
+            "/v1/pipeline-specs",
+            items_key="pipeline_specs",
+            params=params or None,
+            limit=limit,
+        )
+
+    def update_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        topology: dict[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Update pipeline spec settings.
+
+        Args:
+            pipeline_spec_id: ID of the pipeline spec to update.
+            name: New name for the pipeline spec.
+            description: New description.
+            topology: New topology document.
+
+        Returns:
+            Updated pipeline spec record.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if topology is not None:
+            payload["topology"] = topology
+        data = self._request(
+            "PATCH",
+            f"/v1/pipeline-specs/{pipeline_spec_id}",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "PipelineSpecResponse")
+
+    def delete_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> None:
+        """Delete a pipeline spec.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec to delete.
+
+        Returns:
+            None (the API returns 204 No Content on success).
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        self._request(
+            "DELETE",
+            f"/v1/pipeline-specs/{pipeline_spec_id}",
+            request_options=request_options,
+        )
+
+    def get_pipeline_spec_schema(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Retrieve the JSON Schema for pipeline spec topologies.
+
+        Returns:
+            The topology JSON Schema document.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/pipeline-specs/schema", request_options=request_options)
+        # Schema endpoint returns a raw JSON Schema document — no typed model to validate against.
+        return data
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def dry_run_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Perform a dry run of a pipeline spec without creating resources.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The dry run result describing what would be created.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "POST",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/dry-run",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "DryRunResult")
+
+    def apply_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        *,
+        activate_entities: bool = True,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Apply a pipeline spec, creating or updating the described resources.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+            activate_entities: Whether to activate created entities after apply.
+
+        Returns:
+            The apply result describing created/updated resources.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        payload: dict[str, Any] = {"activate_entities": activate_entities}
+        data = self._request(
+            "POST",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/apply",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "ApplyResult")
+
+    def archive_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Archive a pipeline spec.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The archive result.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "POST",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/archive",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "ArchiveResult")
+
+    def unarchive_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Unarchive a previously archived pipeline spec.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The unarchive result.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "POST",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/unarchive",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "PipelineSpecResponse")
+
+    # ------------------------------------------------------------------
+    # Draft
+    # ------------------------------------------------------------------
+
+    def create_pipeline_spec_draft(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Create a draft revision for a pipeline spec.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The newly created draft record.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "POST",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/draft",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "PipelineSpecResponse")
+
+    def get_pipeline_spec_draft(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Retrieve the current draft for a pipeline spec.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The draft record.
+
+        Raises:
+            NotFoundError: If the pipeline spec or draft does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "GET",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/draft",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "PipelineSpecResponse")
+
+    def activate_pipeline_spec_draft(
+        self,
+        pipeline_spec_id: str,
+        *,
+        activate_entities: bool = True,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Activate (apply) the current draft for a pipeline spec.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+            activate_entities: Whether to activate created entities.
+
+        Returns:
+            The draft activation result.
+
+        Raises:
+            NotFoundError: If the pipeline spec or draft does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        payload: dict[str, Any] = {"activate_entities": activate_entities}
+        data = self._request(
+            "POST",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/draft/activate",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "DraftActivateResult")
+
+    def discard_pipeline_spec_draft(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> None:
+        """Discard the current draft for a pipeline spec.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            None (the API returns 204 No Content on success).
+
+        Raises:
+            NotFoundError: If the pipeline spec or draft does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        self._request(
+            "DELETE",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/draft",
+            request_options=request_options,
+        )
+
+    # ------------------------------------------------------------------
+    # Drift
+    # ------------------------------------------------------------------
+
+    def get_pipeline_spec_graph(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Get the graph representation of a pipeline spec topology.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The graph with nodes and edges.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "GET",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/graph",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "GraphResponse")
+
+    def diff_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Get the diff between the pipeline spec and live resources.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The drift report describing differences.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "GET",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/diff",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "DriftReport")
+
+    def refresh_pipeline_spec(
+        self,
+        pipeline_spec_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Refresh a pipeline spec from live resource state.
+
+        Args:
+            pipeline_spec_id: Unique identifier of the pipeline spec.
+
+        Returns:
+            The refresh result.
+
+        Raises:
+            NotFoundError: If the pipeline spec does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        pipeline_spec_id = require_str(pipeline_spec_id, "pipeline_spec_id")
+        data = self._request(
+            "POST",
+            f"/v1/pipeline-specs/{pipeline_spec_id}/refresh",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "RefreshResult")

sdk/resources/projects.py

@@ -0,0 +1,87 @@
+"""Project 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.resources._mixin_base import RequesterMixin
+from sdk.types import ProjectResponse
+
+
+class ProjectsMixin(RequesterMixin):
+    def create_project(
+        self,
+        name: str,
+        *,
+        org_id: str | None = None,
+        org_name: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> ProjectResponse:
+        """Create a new project within an organisation.
+
+        If neither *org_id* nor *org_name* is supplied, the client's
+        default ``org_id`` (if set) is used.
+
+        Args:
+            name: Display name for the project.
+            org_id: Explicit organisation ID to own the project.
+            org_name: Organisation name (resolved server-side if
+                *org_id* is not provided).
+
+        Returns:
+            The newly created project record.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        payload: dict[str, Any] = {"name": name}
+        resolved_org_id = org_id or getattr(self, "org_id", None)
+        if resolved_org_id:
+            payload["org_id"] = resolved_org_id
+        if org_name:
+            payload["org_name"] = org_name
+        data = self._request("POST", "/v1/projects", json=payload, request_options=request_options)
+        return self._maybe_validate(data, "ProjectResponse")
+
+    def list_projects(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List projects accessible to the current credentials.
+
+        Args:
+            limit: Maximum number of projects to return per page.
+            offset: Number of projects to skip for pagination.
+
+        Returns:
+            A Page containing project records with pagination metadata.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        return self._list_page(
+            "GET", "/v1/projects", items_key="projects", limit=limit, offset=offset
+        )
+
+    def iter_projects(
+        self,
+        *,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> SyncPager[dict[str, Any]]:
+        """Iterate over projects, automatically paginating.
+
+        Args:
+            limit: Page size used for each underlying API request.
+
+        Yields:
+            Individual project dicts.
+
+        Raises:
+            Knowledge2Error: If any underlying API request fails.
+        """
+        return self._paginate("GET", "/v1/projects", items_key="projects", limit=limit)