knowledge2 0.4.0__py3-none-any.whl

sdk/async_resources/agents.py

@@ -0,0 +1,489 @@
+"""Async agent resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+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.async_resources._mixin_base import AsyncRequesterMixin
+
+
+@preview_resource
+class AsyncAgentsMixin(AsyncRequesterMixin):
+    async def create_agent(
+        self,
+        *,
+        name: str,
+        corpus_id: str,
+        description: str | None = None,
+        system_prompt: str | None = None,
+        model: str | None = None,
+        project_id: str | None = None,
+        task_type: str | None = None,
+        instructions: str | None = None,
+        source_agents: list[dict[str, Any]] | None = None,
+        tool_config: dict[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Create a new knowledge agent.
+
+        Args:
+            name: Human-readable name for the agent.
+            corpus_id: ID of the corpus the agent queries against.
+            description: Optional description of the agent's purpose.
+            system_prompt: Optional custom system prompt for the agent.
+            model: Optional model identifier (defaults to server-side default).
+            project_id: Optional project that will own the agent.
+            task_type: Optional task type for the agent (e.g. "summarize", "extract").
+            instructions: Optional natural-language instructions for the agent.
+            source_agents: Optional list of source agent references, each with
+                ``agent_id`` and ``mode`` keys.
+            tool_config: Optional tool configuration dictionary for the agent.
+
+        Returns:
+            The newly created agent record.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        payload: dict[str, Any] = {"name": name, "corpus_id": corpus_id}
+        if description is not None:
+            payload["description"] = description
+        if system_prompt is not None:
+            payload["system_prompt"] = system_prompt
+        if model is not None:
+            payload["model"] = model
+        if project_id is not None:
+            payload["project_id"] = project_id
+        if task_type is not None:
+            payload["task_type"] = task_type
+        if instructions is not None:
+            payload["instructions"] = instructions
+        if source_agents is not None:
+            payload["source_agents"] = source_agents
+        if tool_config is not None:
+            payload["tool_config"] = tool_config
+        data = await self._request(
+            "POST", "/v1/agents", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "AgentResponse")
+
+    async def get_agent(
+        self,
+        agent_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Retrieve a single agent by ID.
+
+        Args:
+            agent_id: Unique identifier of the agent.
+
+        Returns:
+            The agent record.
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        data = await self._request("GET", f"/v1/agents/{agent_id}", request_options=request_options)
+        return self._maybe_validate(data, "AgentResponse")
+
+    async def list_agents(
+        self,
+        *,
+        project_id: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List agents accessible to the current credentials.
+
+        Args:
+            project_id: Optional project ID to filter agents by.
+            limit: Maximum number of agents to return per page.
+            offset: Number of agents to skip for pagination.
+
+        Returns:
+            A Page containing agent 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 await self._list_page(
+            "GET",
+            "/v1/agents",
+            items_key="agents",
+            params=params or None,
+            limit=limit,
+            offset=offset,
+        )
+
+    async def update_agent(
+        self,
+        agent_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        corpus_id: str | None = None,
+        system_prompt: str | None = None,
+        model: str | None = None,
+        task_type: str | None = None,
+        instructions: str | None = None,
+        source_agents: list[dict[str, Any]] | None = None,
+        tool_config: dict[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Update agent settings.
+
+        Args:
+            agent_id: ID of the agent to update.
+            name: New name for the agent.
+            description: New description for the agent.
+            corpus_id: New corpus ID for the agent.
+            system_prompt: New system prompt for the agent.
+            model: New model identifier for the agent.
+            task_type: New task type for the agent.
+            instructions: New natural-language instructions for the agent.
+            source_agents: New list of source agent references, each with
+                ``agent_id`` and ``mode`` keys.
+            tool_config: New tool configuration dictionary for the agent.
+
+        Returns:
+            Updated agent record.
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if corpus_id is not None:
+            payload["corpus_id"] = corpus_id
+        if system_prompt is not None:
+            payload["system_prompt"] = system_prompt
+        if model is not None:
+            payload["model"] = model
+        if task_type is not None:
+            payload["task_type"] = task_type
+        if instructions is not None:
+            payload["instructions"] = instructions
+        if source_agents is not None:
+            payload["source_agents"] = source_agents
+        if tool_config is not None:
+            payload["tool_config"] = tool_config
+        data = await self._request(
+            "PATCH", f"/v1/agents/{agent_id}", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "AgentResponse")
+
+    async def delete_agent(
+        self,
+        agent_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> None:
+        """Delete an agent.
+
+        The agent must be in ``draft`` or ``archived`` status; deleting
+        an ``active`` agent will return a 409 Conflict error.
+
+        Args:
+            agent_id: Unique identifier of the agent to delete.
+
+        Returns:
+            None (the API returns 204 No Content on success).
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            ConflictError: If the agent is currently active.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        await self._request("DELETE", f"/v1/agents/{agent_id}", request_options=request_options)
+
+    async def activate_agent(
+        self,
+        agent_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Activate a draft or archived agent.
+
+        Validates that the agent's corpus is ready and model is valid
+        before transitioning the agent to ``active`` status.
+
+        Args:
+            agent_id: Unique identifier of the agent to activate.
+
+        Returns:
+            The updated agent record with ``active`` status.
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            ConflictError: If the agent is already active.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        data = await self._request(
+            "POST", f"/v1/agents/{agent_id}/activate", request_options=request_options
+        )
+        return self._maybe_validate(data, "AgentResponse")
+
+    async def archive_agent(
+        self,
+        agent_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Archive an active agent.
+
+        Transitions the agent from ``active`` to ``archived`` status.
+
+        Args:
+            agent_id: Unique identifier of the agent to archive.
+
+        Returns:
+            The updated agent record with ``archived`` status.
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            ConflictError: If the agent is not currently active.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        data = await self._request(
+            "POST", f"/v1/agents/{agent_id}/archive", request_options=request_options
+        )
+        return self._maybe_validate(data, "AgentResponse")
+
+    async def chat_with_agent(
+        self,
+        agent_id: str,
+        *,
+        query: str,
+        top_k: int = 5,
+        filters: dict[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Send a chat query to an active agent.
+
+        The agent retrieves relevant context from its corpus and generates
+        a grounded answer using its configured model and system prompt.
+
+        Args:
+            agent_id: Unique identifier of the agent to chat with.
+            query: The user's question or prompt.
+            top_k: Number of top search results to use as context.
+            filters: Optional metadata filters to narrow the search scope.
+
+        Returns:
+            A chat response containing the generated answer and sources.
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            ConflictError: If the agent is not active.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        payload: dict[str, Any] = {"query": query, "top_k": top_k}
+        if filters is not None:
+            payload["filters"] = filters
+        data = await self._request(
+            "POST",
+            f"/v1/agents/{agent_id}/chat",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "AgentChatResponse")
+
+    async def list_agent_models(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """List available models for knowledge agents.
+
+        Returns:
+            A dict containing the list of supported model identifiers.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = await self._request("GET", "/v1/agents/models", request_options=request_options)
+        return self._maybe_validate(data, "AgentModelsResponse")
+
+    async def run_agent(
+        self,
+        agent_id: str,
+        *,
+        input_chunks: list[dict[str, Any]],
+        top_k: int = 5,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Run an agent on a set of input chunks.
+
+        The endpoint returns HTTP 202 and the task is queued as a background
+        job. Poll ``list_agent_runs()`` or the Jobs API to check for
+        completion.
+
+        Args:
+            agent_id: Unique identifier of the agent to run.
+            input_chunks: List of input chunk dicts, each containing a ``text``
+                key and an optional ``metadata`` key.
+            top_k: Number of top search results to use as context.
+
+        Returns:
+            A dict containing ``job_id`` and ``status`` for the queued run.
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        payload: dict[str, Any] = {"input_chunks": input_chunks, "top_k": top_k}
+        data = await self._request(
+            "POST",
+            f"/v1/agents/{agent_id}/run",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "AgentRunResponse")
+
+    async def list_agent_runs(
+        self,
+        agent_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List runs for a given agent.
+
+        Args:
+            agent_id: Unique identifier of the agent.
+            limit: Maximum number of runs to return per page.
+            offset: Number of runs to skip for pagination.
+
+        Returns:
+            A Page containing agent run records with pagination metadata.
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        return await self._list_page(
+            "GET",
+            f"/v1/agents/{agent_id}/runs",
+            items_key="runs",
+            limit=limit,
+            offset=offset,
+        )
+
+    async def list_task_types(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """List available task types for knowledge agents.
+
+        Returns:
+            A dict containing the list of supported task type identifiers.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = await self._request("GET", "/v1/agents/task-types", request_options=request_options)
+        return self._maybe_validate(data, "AgentTaskTypesResponse")
+
+    async def create_subscription(
+        self,
+        agent_id: str,
+        *,
+        feed_id: str,
+        role: Literal["input", "output"],
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """Create a feed subscription for an agent.
+
+        Args:
+            agent_id: Unique identifier of the agent.
+            feed_id: Unique identifier of the feed to subscribe to.
+            role: Subscription role, either ``"input"`` or ``"output"``.
+
+        Returns:
+            The newly created subscription record.
+
+        Raises:
+            NotFoundError: If the agent or feed does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        feed_id = require_str(feed_id, "feed_id")
+        payload: dict[str, Any] = {"feed_id": feed_id, "role": role}
+        data = await self._request(
+            "POST",
+            f"/v1/agents/{agent_id}/subscriptions",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "SubscriptionResponse")
+
+    async def list_subscriptions(
+        self,
+        agent_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> dict[str, Any]:
+        """List all feed subscriptions for an agent.
+
+        Args:
+            agent_id: Unique identifier of the agent.
+
+        Returns:
+            A dict containing the list of subscription records.
+
+        Raises:
+            NotFoundError: If the agent does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        data = await self._request(
+            "GET",
+            f"/v1/agents/{agent_id}/subscriptions",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "SubscriptionListResponse")
+
+    async def delete_subscription(
+        self,
+        agent_id: str,
+        subscription_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> None:
+        """Delete a feed subscription from an agent.
+
+        Args:
+            agent_id: Unique identifier of the agent.
+            subscription_id: Unique identifier of the subscription to delete.
+
+        Returns:
+            None (the API returns 204 No Content on success).
+
+        Raises:
+            NotFoundError: If the agent or subscription does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        agent_id = require_str(agent_id, "agent_id")
+        subscription_id = require_str(subscription_id, "subscription_id")
+        await self._request(
+            "DELETE",
+            f"/v1/agents/{agent_id}/subscriptions/{subscription_id}",
+            request_options=request_options,
+        )

sdk/async_resources/audit.py

@@ -0,0 +1,145 @@
+"""Async audit-log 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.async_resources._mixin_base import AsyncRequesterMixin
+from sdk.types import AuditLogActionsResponse
+
+
+class AsyncAuditMixin(AsyncRequesterMixin):
+    async def list_audit_logs(
+        self,
+        *,
+        corpus_id: str | None = None,
+        project_id: str | None = None,
+        action: str | None = None,
+        entity_type: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        user_id: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List audit log entries with optional filters.
+
+        Args:
+            corpus_id: Filter logs to a specific corpus.
+            project_id: Filter logs to a specific project.
+            action: Filter logs by action type.
+            entity_type: Filter logs by entity type.
+            since: Filter logs created on or after this ISO 8601 timestamp.
+            until: Filter logs created before this ISO 8601 timestamp.
+            user_id: Filter logs by the acting user.
+            limit: Maximum number of entries to return per page.
+            offset: Number of entries to skip for pagination.
+
+        Returns:
+            A Page containing audit log entries with pagination metadata.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        params: dict[str, Any] = {}
+        if corpus_id:
+            params["corpus_id"] = corpus_id
+        if project_id:
+            params["project_id"] = project_id
+        if action:
+            params["action"] = action
+        if entity_type:
+            params["entity_type"] = entity_type
+        if since:
+            params["since"] = since
+        if until:
+            params["until"] = until
+        if user_id:
+            params["user_id"] = user_id
+        return await self._list_page(
+            "GET",
+            "/v1/audit-logs",
+            items_key="logs",
+            params=params or None,
+            limit=limit,
+            offset=offset,
+        )
+
+    def iter_audit_logs(
+        self,
+        *,
+        corpus_id: str | None = None,
+        project_id: str | None = None,
+        action: str | None = None,
+        entity_type: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        user_id: str | None = None,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> AsyncPager[dict[str, Any]]:
+        """Iterate over audit logs, automatically paginating.
+
+        Args:
+            corpus_id: Filter logs to a specific corpus.
+            project_id: Filter logs to a specific project.
+            action: Filter logs by action type.
+            entity_type: Filter logs by entity type.
+            since: Filter logs created on or after this ISO 8601 timestamp.
+            until: Filter logs created before this ISO 8601 timestamp.
+            user_id: Filter logs by the acting user.
+            limit: Page size used for each underlying API request.
+
+        Yields:
+            Individual audit log entry dicts.
+
+        Raises:
+            Knowledge2Error: If any underlying API request fails.
+        """
+        params: dict[str, Any] = {}
+        if corpus_id:
+            params["corpus_id"] = corpus_id
+        if project_id:
+            params["project_id"] = project_id
+        if action:
+            params["action"] = action
+        if entity_type:
+            params["entity_type"] = entity_type
+        if since:
+            params["since"] = since
+        if until:
+            params["until"] = until
+        if user_id:
+            params["user_id"] = user_id
+        return self._paginate(
+            "GET", "/v1/audit-logs", items_key="logs", params=params or None, limit=limit
+        )
+
+    async def list_audit_actions(
+        self,
+        *,
+        user_id: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> AuditLogActionsResponse:
+        """List distinct audit action types that have occurred in the organization.
+
+        Args:
+            user_id: Filter actions to those performed by a specific user.
+
+        Returns:
+            An object containing the list of distinct action type strings.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        params: dict[str, Any] = {}
+        if user_id:
+            params["user_id"] = user_id
+        data = await self._request(
+            "GET", "/v1/audit-logs/actions", params=params or None, request_options=request_options
+        )
+        return self._maybe_validate(data, "AuditLogActionsResponse")