deepset-mcp 0.0.2rc1__py3-none-any.whl

deepset_mcp/api/client.py

@@ -0,0 +1,277 @@
+import os
+from collections.abc import AsyncIterator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from types import TracebackType
+from typing import Any, Literal, Self, TypeVar, overload
+
+from deepset_mcp.api.custom_components.resource import CustomComponentsResource
+from deepset_mcp.api.haystack_service.resource import HaystackServiceResource
+from deepset_mcp.api.indexes.resource import IndexResource
+from deepset_mcp.api.integrations.resource import IntegrationResource
+from deepset_mcp.api.pipeline.resource import PipelineResource
+from deepset_mcp.api.pipeline_template.resource import PipelineTemplateResource
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.secrets.resource import SecretResource
+from deepset_mcp.api.transport import (
+    AsyncTransport,
+    StreamingResponse,
+    TransportProtocol,
+    TransportResponse,
+)
+from deepset_mcp.api.user.resource import UserResource
+from deepset_mcp.api.workspace.resource import WorkspaceResource
+
+T = TypeVar("T")
+
+
+class AsyncDeepsetClient(AsyncClientProtocol):
+    """Async Client for interacting with the deepset API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.cloud.deepset.ai/api",
+        transport: TransportProtocol | None = None,
+        transport_config: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Initialize an instance of the AsyncDeepsetClient.
+
+        Parameters
+        ----------
+        api_key : str, optional
+            API key or token. Falls back to DEEPSET_API_KEY env var.
+        base_url : str, optional
+            Base URL for the deepset API.
+        transport : TransportProtocol, optional
+            Custom transport implementation.
+        transport_config : dict, optional
+            Configuration for default transport (e.g. timeout).
+        """
+        self.api_key = api_key or os.environ.get("DEEPSET_API_KEY")
+        if not self.api_key:
+            raise ValueError("API key not provided and DEEPSET_API_KEY environment variable not set")
+        self.base_url = base_url
+        if transport is not None:
+            self._transport = transport
+        else:
+            self._transport = AsyncTransport(
+                base_url=self.base_url,
+                api_key=self.api_key,
+                config=transport_config,
+            )
+
+    @overload
+    async def request(
+        self,
+        endpoint: str,
+        *,
+        response_type: type[T],
+        method: str = "GET",
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[T]: ...
+
+    @overload
+    async def request(
+        self,
+        endpoint: str,
+        *,
+        response_type: None = None,
+        method: str = "GET",
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[Any]: ...
+
+    async def request(
+        self,
+        endpoint: str,
+        *,
+        method: str = "GET",
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        response_type: type[T] | None = None,
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[Any]:
+        """
+        Make a regular (non-streaming) request to the deepset API.
+
+        Parameters
+        ----------
+        endpoint : str
+            API endpoint path
+        method : str, default="GET"
+            HTTP method
+        data : dict, optional
+            JSON data to send in request body
+        headers : dict, optional
+            Additional headers to include
+        response_type : type[T], optional
+            Expected response type for type checking
+        timeout : float | None | Literal["config"], optional
+            Request timeout in seconds. If "config", uses transport config timeout.
+            If None, disables timeout. If float, uses specific timeout.
+        **kwargs : Any
+            Additional arguments to pass to transport
+
+        Returns
+        -------
+        TransportResponse[T]
+            Response with parsed JSON if available
+        """
+        if not endpoint.startswith("/"):
+            endpoint = f"/{endpoint}"
+        url = self.base_url + endpoint
+
+        # Default headers
+        request_headers: dict[str, str] = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json,text/plain,*/*",
+        }
+        if data is not None:
+            request_headers["Content-Type"] = "application/json"
+        # Merge custom headers
+        if headers:
+            headers.setdefault("Authorization", request_headers["Authorization"])
+            request_headers.update(headers)
+
+        return await self._transport.request(
+            method,
+            url,
+            json=data,
+            headers=request_headers,
+            response_type=response_type,
+            timeout=timeout,
+            **kwargs,
+        )
+
+    def stream_request(
+        self,
+        endpoint: str,
+        *,
+        method: str = "POST",
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> AbstractAsyncContextManager[StreamingResponse]:
+        """
+        Make a streaming request to the deepset API.
+
+        Must be used as an async context manager to ensure proper cleanup.
+
+        Parameters
+        ----------
+        endpoint : str
+            API endpoint path
+        method : str, default="POST"
+            HTTP method (usually POST for streaming)
+        data : dict, optional
+            JSON data to send in request body
+        headers : dict, optional
+            Additional headers to include
+        **kwargs : Any
+            Additional arguments to pass to transport
+
+        Yields
+        ------
+        StreamingResponse
+            Response object with streaming capabilities
+
+        Examples
+        --------
+        async with client.stream_request("/pipelines/search-stream", data={"query": "AI"}) as response:
+            if response.success:
+                async for line in response.iter_lines():
+                    # Process each line of the stream
+                    data = json.loads(line)
+                    print(data)
+            else:
+                # Handle error
+                error_body = await response.read_body()
+                print(f"Error {response.status_code}: {error_body}")
+        """
+
+        @asynccontextmanager
+        async def _stream() -> AsyncIterator[StreamingResponse]:
+            if not endpoint.startswith("/"):
+                full_endpoint = f"/{endpoint}"
+            url = self.base_url + full_endpoint
+
+            # Default headers for streaming
+            request_headers: dict[str, str] = {
+                "Authorization": f"Bearer {self.api_key}",
+                "Accept": "text/event-stream,application/json,text/plain,*/*",
+            }
+            if data is not None:
+                request_headers["Content-Type"] = "application/json"
+            # Merge custom headers
+            if headers:
+                headers.setdefault("Authorization", request_headers["Authorization"])
+                request_headers.update(headers)
+
+            async with self._transport.stream(
+                method,
+                url,
+                json=data,
+                headers=request_headers,
+                **kwargs,
+            ) as response:
+                yield response
+
+        return _stream()
+
+    async def close(self) -> None:
+        """Close underlying transport resources."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> Self:
+        """Enter the AsyncContextManager."""
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None
+    ) -> bool:
+        """Exit the AsyncContextmanager and clean up resources."""
+        await self.close()
+        return False
+
+    def pipelines(self, workspace: str) -> PipelineResource:
+        """Resource to interact with pipelines in the specified workspace."""
+        return PipelineResource(client=self, workspace=workspace)
+
+    def haystack_service(self) -> HaystackServiceResource:
+        """Resource to interact with the Haystack service API."""
+        return HaystackServiceResource(client=self)
+
+    def pipeline_templates(self, workspace: str) -> PipelineTemplateResource:
+        """Resource to interact with pipeline templates in the specified workspace."""
+        return PipelineTemplateResource(client=self, workspace=workspace)
+
+    def indexes(self, workspace: str) -> IndexResource:
+        """Resource to interact with indexes in the specified workspace."""
+        return IndexResource(client=self, workspace=workspace)
+
+    def custom_components(self, workspace: str) -> CustomComponentsResource:
+        """Resource to interact with custom components in the specified workspace."""
+        return CustomComponentsResource(client=self)
+
+    def users(self) -> UserResource:
+        """Resource to interact with users."""
+        return UserResource(client=self)
+
+    def secrets(self) -> SecretResource:
+        """Resource to interact with secrets."""
+        return SecretResource(client=self)
+
+    def workspaces(self) -> WorkspaceResource:
+        """Resource to interact with workspaces."""
+        return WorkspaceResource(client=self)
+
+    def integrations(self) -> IntegrationResource:
+        """Resource to interact with integrations."""
+        return IntegrationResource(client=self)

deepset_mcp/api/custom_components/models.py

@@ -0,0 +1,25 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+from deepset_mcp.api.shared_models import DeepsetUser
+
+
+class CustomComponentInstallation(BaseModel):
+    """Model representing a custom component installation."""
+
+    custom_component_id: str
+    status: str
+    version: str
+    created_by_user_id: str
+    logs: list[dict[str, Any]]
+    organization_id: str
+    user_info: DeepsetUser | None = None
+
+
+class CustomComponentInstallationList(BaseModel):
+    """Model representing a list of custom component installations."""
+
+    data: list[CustomComponentInstallation]
+    total: int
+    has_more: bool

deepset_mcp/api/custom_components/protocols.py

@@ -0,0 +1,17 @@
+from typing import Protocol
+
+from deepset_mcp.api.custom_components.models import CustomComponentInstallationList
+
+
+class CustomComponentsProtocol(Protocol):
+    """Protocol defining the implementation for CustomComponentsResource."""
+
+    async def list_installations(
+        self, limit: int = 20, page_number: int = 1, field: str = "created_at", order: str = "DESC"
+    ) -> CustomComponentInstallationList:
+        """List custom component installations."""
+        ...
+
+    async def get_latest_installation_logs(self) -> str | None:
+        """Get the logs from the latest custom component installation."""
+        ...

deepset_mcp/api/custom_components/resource.py

@@ -0,0 +1,56 @@
+from typing import Any
+
+from deepset_mcp.api.custom_components.models import CustomComponentInstallationList
+from deepset_mcp.api.custom_components.protocols import CustomComponentsProtocol
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.transport import raise_for_status
+
+
+class CustomComponentsResource(CustomComponentsProtocol):
+    """Resource for managing custom components in deepset."""
+
+    def __init__(self, client: AsyncClientProtocol) -> None:
+        """Initialize a CustomComponentsResource.
+
+        :param client: The API client to use for requests.
+        """
+        self._client = client
+
+    async def list_installations(
+        self, limit: int = 20, page_number: int = 1, field: str = "created_at", order: str = "DESC"
+    ) -> CustomComponentInstallationList:
+        """List custom component installations.
+
+        :param limit: Maximum number of installations to return.
+        :param page_number: Page number for pagination.
+        :param field: Field to sort by.
+        :param order: Sort order (ASC or DESC).
+
+        :returns: List of custom component installations.
+        """
+        resp = await self._client.request(
+            endpoint=f"v2/custom_components?limit={limit}&page_number={page_number}&field={field}&order={order}",
+            method="GET",
+            response_type=dict[str, Any],
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is None:
+            return CustomComponentInstallationList(data=[], total=0, has_more=False)
+
+        return CustomComponentInstallationList(**resp.json)
+
+    async def get_latest_installation_logs(self) -> str | None:
+        """Get the logs from the latest custom component installation.
+
+        :returns: Latest installation logs.
+        """
+        resp = await self._client.request(
+            endpoint="v2/custom_components/logs",
+            method="GET",
+        )
+
+        raise_for_status(resp)
+
+        return resp.text

deepset_mcp/api/exceptions.py

@@ -0,0 +1,70 @@
+from typing import Any
+
+
+class DeepsetAPIError(Exception):
+    """Base exception for all deepset API errors."""
+
+    def __init__(self, status_code: int | None = None, message: Any | None = None, detail: Any | None = None) -> None:
+        """Initialize the exception."""
+        self.status_code = status_code
+        self.message = message
+        self.detail = detail
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        """Return a string representation of the exception."""
+        return f"{self.message} (Status Code: {self.status_code})"
+
+
+class ResourceNotFoundError(DeepsetAPIError):
+    """Exception raised when a resource is not found (HTTP 404)."""
+
+    def __init__(self, message: Any = "Resource not found", detail: Any | None = None) -> None:
+        """Initialize the exception."""
+        super().__init__(status_code=404, message=message, detail=detail)
+
+
+class BadRequestError(DeepsetAPIError):
+    """Exception raised for invalid requests (HTTP 400)."""
+
+    def __init__(self, message: Any = "Bad request", detail: Any | None = None) -> None:
+        """Initialize the exception."""
+        super().__init__(status_code=400, message=message, detail=detail)
+
+
+class RequestTimeoutError(Exception):
+    """Exception raised when a request times out."""
+
+    def __init__(
+        self,
+        method: str,
+        url: str,
+        timeout: float | None | str,
+        duration: float | None = None,
+        detail: str | None = None,
+    ):
+        """Initialize the timeout exception with request context."""
+        self.method = method
+        self.url = url
+        self.timeout = timeout
+        self.duration = duration
+        self.detail = detail
+
+        timeout_display = f"{timeout}s" if isinstance(timeout, int | float) else str(timeout)
+
+        if duration is not None:
+            message = f"Request timed out after {duration:.2f}s (limit: {timeout_display}): {method} {url}"
+        else:
+            message = f"Request timed out (limit: {timeout_display}): {method} {url}"
+
+        super().__init__(message)
+
+
+class UnexpectedAPIError(DeepsetAPIError):
+    """Catch-all exception for unexpected API errors."""
+
+    def __init__(
+        self, status_code: int | None = None, message: Any = "Unexpected API error", detail: Any | None = None
+    ):
+        """Initialize the exception."""
+        super().__init__(status_code=status_code, message=message, detail=detail)

deepset_mcp/api/haystack_service/protocols.py

@@ -0,0 +1,13 @@
+from typing import Any, Protocol
+
+
+class HaystackServiceProtocol(Protocol):
+    """Protocol defining the implementation for HaystackService."""
+
+    async def get_component_schemas(self) -> dict[str, Any]:
+        """Fetch the component schema from the API."""
+        ...
+
+    async def get_component_input_output(self, component_name: str) -> dict[str, Any]:
+        """Fetch input and output schema for a component from the API."""
+        ...

deepset_mcp/api/haystack_service/resource.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+from deepset_mcp.api.exceptions import ResourceNotFoundError
+from deepset_mcp.api.haystack_service.protocols import HaystackServiceProtocol
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.transport import raise_for_status
+
+
+class HaystackServiceResource(HaystackServiceProtocol):
+    """Manages interactions with the deepset Haystack service API."""
+
+    def __init__(self, client: AsyncClientProtocol) -> None:
+        """Initializes a HaystackServiceResource instance."""
+        self._client = client
+
+    async def get_component_schemas(self) -> dict[str, Any]:
+        """Fetch the component schema from the API.
+
+        Returns:
+            The component schema as a dictionary
+        """
+        resp = await self._client.request(
+            endpoint="v1/haystack/components",
+            method="GET",
+            headers={"accept": "application/json"},
+            data={"domain": "deepset-cloud"},
+        )
+
+        raise_for_status(resp)
+
+        return resp.json if resp.json is not None else {}
+
+    async def get_component_input_output(self, component_name: str) -> dict[str, Any]:
+        """Fetch the component input and output schema from the API.
+
+        Args:
+            component_name: The name of the component to fetch the input/output schema for
+
+        Returns:
+            The component input/output schema as a dictionary
+        """
+        resp = await self._client.request(
+            endpoint="v1/haystack/components/input-output",
+            method="GET",
+            headers={"accept": "application/json"},
+            params={"domain": "deepset-cloud", "names": component_name},
+            response_type=list[dict[str, Any]],
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is None or len(resp.json) == 0:
+            raise ResourceNotFoundError(f"Component '{component_name}' not found.")
+
+        return resp.json[0] if resp.json is not None else {}

deepset_mcp/api/indexes/models.py

@@ -0,0 +1,63 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+from rich.repr import Result
+
+from deepset_mcp.api.shared_models import DeepsetUser
+
+
+class IndexStatus(BaseModel):
+    """Status information about documents in an index."""
+
+    pending_file_count: int
+    failed_file_count: int
+    indexed_no_documents_file_count: int
+    indexed_file_count: int
+    total_file_count: int
+
+
+class Index(BaseModel):
+    """A deepset index."""
+
+    pipeline_index_id: str
+    name: str
+    description: str | None = None
+    config_yaml: str
+    workspace_id: str
+    settings: dict[str, Any]
+    desired_status: str
+    deployed_at: datetime | None = None
+    last_edited_at: datetime | None = None
+    max_index_replica_count: int
+    created_at: datetime
+    updated_at: datetime | None = None
+    created_by: DeepsetUser
+    last_edited_by: DeepsetUser | None = None
+    status: IndexStatus
+
+    def __rich_repr__(self) -> Result:
+        """Used to display the model in an LLM friendly way."""
+        yield "name", self.name
+        yield "description", self.description, None
+        yield "desired_status", self.desired_status
+        yield "status", self.status
+        yield "status", self.status
+        yield "created_by", f"{self.created_by.given_name} {self.created_by.family_name} ({self.created_by.id})"
+        yield "created_at", self.created_at.strftime("%m/%d/%Y %I:%M:%S %p")
+        yield (
+            "last_edited_by",
+            f"{self.last_edited_by.given_name} {self.last_edited_by.family_name} ({self.last_edited_by.id})"
+            if self.last_edited_by
+            else None,
+        )
+        yield "last_edited_at", self.last_edited_at.strftime("%m/%d/%Y %I:%M:%S %p") if self.last_edited_at else None
+        yield "config_yaml", self.config_yaml if self.config_yaml is not None else "Get full index to see config."
+
+
+class IndexList(BaseModel):
+    """Response model for listing indexes."""
+
+    data: list[Index]
+    has_more: bool
+    total: int

deepset_mcp/api/indexes/protocols.py

@@ -0,0 +1,53 @@
+from typing import Protocol
+
+from deepset_mcp.api.indexes.models import Index, IndexList
+from deepset_mcp.api.pipeline.models import PipelineValidationResult
+
+
+class IndexResourceProtocol(Protocol):
+    """Protocol defining the implementation for IndexResource."""
+
+    async def list(self, limit: int = 10, page_number: int = 1) -> IndexList:
+        """List indexes in the configured workspace."""
+        ...
+
+    async def get(self, index_name: str) -> Index:
+        """Fetch a single index by its name."""
+        ...
+
+    async def create(self, name: str, yaml_config: str, description: str | None = None) -> Index:
+        """Create a new index with the given name and configuration.
+
+        :param name: Name of the index
+        :param yaml_config: YAML configuration for the index
+        :param description: Optional description for the index
+        :returns: Created index details
+        """
+        ...
+
+    async def update(
+        self, index_name: str, updated_index_name: str | None = None, yaml_config: str | None = None
+    ) -> Index:
+        """Update name and/or configuration of an existing index.
+
+        :param index_name: Name of the index to update
+        :param updated_index_name: Optional new name for the index
+        :param yaml_config: Optional new YAML configuration
+        :returns: Updated index details
+        """
+        ...
+
+    async def deploy(self, index_name: str) -> PipelineValidationResult:
+        """Deploy an index to production.
+
+        :param index_name: Name of the index to deploy.
+        :returns: PipelineValidationResult containing deployment status and any errors.
+        """
+        ...
+
+    async def delete(self, index_name: str) -> None:
+        """Delete an index.
+
+        :param index_name: Name of the index to delete.
+        """
+        ...