deepset-mcp 0.0.2__py3-none-any.whl

deepset_mcp/api/secrets/protocols.py

@@ -0,0 +1,29 @@
+from typing import Protocol
+
+from deepset_mcp.api.secrets.models import Secret, SecretList
+from deepset_mcp.api.shared_models import NoContentResponse
+
+
+class SecretResourceProtocol(Protocol):
+    """Protocol defining the implementation for SecretResource."""
+
+    async def list(
+        self,
+        limit: int = 10,
+        field: str = "created_at",
+        order: str = "DESC",
+    ) -> SecretList:
+        """List secrets with pagination."""
+        ...
+
+    async def create(self, name: str, secret: str) -> NoContentResponse:
+        """Create a new secret."""
+        ...
+
+    async def get(self, secret_id: str) -> Secret:
+        """Get a specific secret by ID."""
+        ...
+
+    async def delete(self, secret_id: str) -> NoContentResponse:
+        """Delete a secret by ID."""
+        ...

deepset_mcp/api/secrets/resource.py

@@ -0,0 +1,112 @@
+from typing import Any
+
+from deepset_mcp.api.exceptions import ResourceNotFoundError
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.secrets.models import Secret, SecretList
+from deepset_mcp.api.secrets.protocols import SecretResourceProtocol
+from deepset_mcp.api.shared_models import NoContentResponse
+from deepset_mcp.api.transport import raise_for_status
+
+
+class SecretResource(SecretResourceProtocol):
+    """Resource for managing secrets in deepset."""
+
+    def __init__(self, client: AsyncClientProtocol) -> None:
+        """Initialize a SecretResource.
+
+        :param client: The API client to use for requests.
+        """
+        self._client = client
+
+    async def list(
+        self,
+        limit: int = 10,
+        field: str = "created_at",
+        order: str = "DESC",
+    ) -> SecretList:
+        """List secrets with pagination.
+
+        :param limit: Maximum number of secrets to return.
+        :param field: Field to sort by.
+        :param order: Sort order (ASC or DESC).
+
+        :returns: List of secrets with pagination info.
+        """
+        params = {
+            "limit": str(limit),
+            "field": field,
+            "order": order,
+        }
+
+        resp = await self._client.request(
+            endpoint="v2/secrets",
+            method="GET",
+            response_type=dict[str, Any],
+            params=params,
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is None:
+            raise ResourceNotFoundError("Failed to retrieve secrets.")
+
+        return SecretList(**resp.json)
+
+    async def create(self, name: str, secret: str) -> NoContentResponse:
+        """Create a new secret.
+
+        :param name: The name of the secret.
+        :param secret: The secret value.
+
+        :returns: NoContentResponse indicating successful creation.
+        """
+        data = {
+            "name": name,
+            "secret": secret,
+        }
+
+        resp = await self._client.request(
+            endpoint="v2/secrets",
+            method="POST",
+            data=data,
+            response_type=None,
+        )
+
+        raise_for_status(resp)
+        return NoContentResponse(message="Secret created successfully.")
+
+    async def get(self, secret_id: str) -> Secret:
+        """Get a specific secret by ID.
+
+        :param secret_id: The ID of the secret to retrieve.
+
+        :returns: Secret information.
+        """
+        resp = await self._client.request(
+            endpoint=f"v2/secrets/{secret_id}",
+            method="GET",
+            response_type=dict[str, Any],
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is None:
+            raise ResourceNotFoundError(f"Secret '{secret_id}' not found.")
+
+        return Secret(**resp.json)
+
+    async def delete(self, secret_id: str) -> NoContentResponse:
+        """Delete a secret by ID.
+
+        :param secret_id: The ID of the secret to delete.
+
+        :returns: NoContentResponse indicating successful deletion.
+        """
+        resp = await self._client.request(
+            endpoint=f"v2/secrets/{secret_id}",
+            method="DELETE",
+            response_type=None,
+        )
+
+        raise_for_status(resp)
+        return NoContentResponse(message="Secret deleted successfully.")

deepset_mcp/api/shared_models.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field
+
+
+class NoContentResponse(BaseModel):
+    """Response model for an empty response."""
+
+    success: bool = True
+    message: str = "No content"
+
+
+class DeepsetUser(BaseModel):
+    """Model representing a user on the deepset platform."""
+
+    id: str = Field(alias="user_id")
+    given_name: str | None = None
+    family_name: str | None = None
+    email: str | None = None

deepset_mcp/api/transport.py

@@ -0,0 +1,336 @@
+import json
+import time
+from collections.abc import AsyncIterator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Generic, Literal, Protocol, TypeVar, cast, overload
+
+import httpx
+
+from deepset_mcp.api.exceptions import BadRequestError, RequestTimeoutError, ResourceNotFoundError, UnexpectedAPIError
+
+T = TypeVar("T")
+
+
+class StreamReaderProtocol(Protocol):
+    """Protocol for reading from a stream."""
+
+    async def aread(self) -> bytes:
+        """Read the entire response body."""
+        ...
+
+    def aiter_lines(self) -> AsyncIterator[str]:
+        """Iterate over response lines."""
+        ...
+
+
+@dataclass
+class TransportResponse(Generic[T]):
+    """Response envelope for regular HTTP transport."""
+
+    text: str
+    status_code: int
+    json: T | None = None
+
+    @property
+    def success(self) -> bool:
+        """Check if the response was successful (status code < 400)."""
+        return self.status_code < 400
+
+
+@dataclass
+class StreamingResponse:
+    """Response envelope for streaming HTTP transport."""
+
+    status_code: int
+    headers: dict[str, str]
+    _reader: StreamReaderProtocol
+
+    @property
+    def success(self) -> bool:
+        """Check if the response was successful (status code < 400)."""
+        return self.status_code < 400
+
+    async def iter_lines(self) -> AsyncIterator[str]:
+        """
+        Iterate over response lines.
+
+        For error responses (status >= 400), reads the entire body and yields it.
+        For success responses, yields line by line.
+        """
+        if self.status_code >= 400:
+            # For errors, read entire body at once
+            body = await self._reader.aread()
+            if body:
+                yield body.decode()
+        else:
+            # For success, stream line by line
+            async for line in self._reader.aiter_lines():
+                if line.startswith("data: "):  # optionally handle SSE 'data: ' prefix
+                    yield line[6:]
+                yield line
+
+    async def read_body(self) -> str:
+        """Read the entire response body. Useful for error handling."""
+        body = await self._reader.aread()
+        return body.decode() if body else ""
+
+
+def raise_for_status(response: TransportResponse[Any]) -> None:
+    """Raises the appropriate exception based on the response status code."""
+    if response.success:
+        return
+
+    # Map status codes to exception classes
+    exception_map = {
+        400: BadRequestError,
+        404: ResourceNotFoundError,
+    }
+
+    if isinstance(response.json, dict):
+        detail = response.json.get("details") if response.json else None
+        message = response.json.get("message") if response.json else response.text
+    else:
+        detail = json.dumps(response.json) if response.json else None
+        message = response.text
+
+    # Get exception class
+    exception_class = exception_map.get(response.status_code)
+
+    if exception_class:
+        # For specific exceptions (BadRequestError, ResourceNotFoundError)
+        raise exception_class(message=message, detail=detail)
+    else:
+        # For the catch-all case, include the status code
+        raise UnexpectedAPIError(
+            status_code=response.status_code, message=message or "Unexpected API error", detail=detail
+        )
+
+
+class TransportProtocol(Protocol):
+    """Protocol for HTTP transport with separate streaming support."""
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        response_type: type[T],
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[T]: ...
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        response_type: None = None,
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[Any]: ...
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        response_type: type[T] | None = None,
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[Any]:
+        """Send a regular HTTP request and return the response."""
+        ...
+
+    def stream(self, method: str, url: str, **kwargs: Any) -> AbstractAsyncContextManager[StreamingResponse]:
+        """
+        Open a streaming HTTP connection.
+
+        Must be used as an async context manager to ensure proper cleanup.
+        """
+        ...
+
+    async def close(self) -> None:
+        """Clean up any resources (e.g., close connections)."""
+        ...
+
+
+class _HttpxStreamReader:
+    """Adapter to make httpx.Response conform to StreamReaderProtocol."""
+
+    def __init__(self, response: httpx.Response):
+        self._response = response
+
+    async def aread(self) -> bytes:
+        """Read the entire response body."""
+        return await self._response.aread()
+
+    async def aiter_lines(self) -> AsyncIterator[str]:
+        """Iterate over response lines."""
+        async for line in self._response.aiter_lines():
+            yield line
+
+
+class AsyncTransport:
+    """Asynchronous HTTP transport using httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        config: dict[str, Any] | None = None,
+    ):
+        """
+        Initialize an instance of AsyncTransport.
+
+        Parameters
+        ----------
+        base_url : str
+            Base URL for the API
+        api_key : str
+            Bearer token for authentication
+        config : dict, optional
+            Configuration for httpx.AsyncClient, e.g., {'timeout': 10.0}
+        """
+        config = config or {}
+        # Ensure auth header
+        headers = config.pop("headers", {})
+        headers.setdefault("Authorization", f"Bearer {api_key}")
+        # Build client kwargs
+        client_kwargs = {
+            "base_url": base_url,
+            "headers": headers,
+            **config,
+        }
+        self._client = httpx.AsyncClient(**client_kwargs)
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        response_type: type[T],
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[T]: ...
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        response_type: None = None,
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[Any]: ...
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        response_type: type[T] | None = None,
+        timeout: float | None | Literal["config"] = "config",
+        **kwargs: Any,
+    ) -> TransportResponse[Any]:
+        """
+        Send a regular HTTP request and return the response.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method
+        url : str
+            URL endpoint
+        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 httpx
+
+        Returns
+        -------
+        TransportResponse[T]
+            The response with parsed JSON if available
+        """
+        if timeout != "config":
+            kwargs["timeout"] = timeout
+
+        start_time = time.time()
+        try:
+            response = await self._client.request(method, url, **kwargs)
+        except httpx.TimeoutException as e:
+            duration = time.time() - start_time
+            timeout_value = kwargs.get("timeout", "config default")
+
+            detail = None
+            if "search" in url and duration > 60:
+                detail = (
+                    "Search operations can take longer with large document collections or complex pipelines. "
+                    "Consider increasing the timeout for search requests."
+                )
+
+            raise RequestTimeoutError(
+                method=method, url=url, timeout=timeout_value, duration=duration, detail=detail
+            ) from e
+
+        if response_type is not None:
+            raw = response.json()
+            payload: T = cast(T, raw)
+            return TransportResponse(text=response.text, status_code=response.status_code, json=payload)
+
+        try:
+            untyped_response = response.json()
+        except json.JSONDecodeError:
+            untyped_response = None
+
+        return TransportResponse(text=response.text, status_code=response.status_code, json=untyped_response)
+
+    def stream(self, method: str, url: str, **kwargs: Any) -> AbstractAsyncContextManager[StreamingResponse]:
+        """
+        Open a streaming HTTP connection.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method
+        url : str
+            URL endpoint
+        **kwargs : Any
+            Additional arguments to pass to httpx.stream()
+
+        Yields
+        ------
+        StreamingResponse
+            Response object with streaming capabilities
+
+        Examples
+        --------
+        async with transport.stream("POST", "/api/stream", json=data) as response:
+            if response.success:
+                async for line in response.iter_lines():
+                    process_line(line)
+            else:
+                error = await response.read_body()
+                handle_error(error)
+        """
+
+        @asynccontextmanager
+        async def _stream() -> AsyncIterator[StreamingResponse]:
+            async with self._client.stream(method, url, **kwargs) as response:
+                reader = _HttpxStreamReader(response)
+                yield StreamingResponse(
+                    status_code=response.status_code, headers=dict(response.headers), _reader=reader
+                )
+
+        return _stream()
+
+    async def close(self) -> None:
+        """Clean up any resources (e.g., close connections)."""
+        await self._client.aclose()

deepset_mcp/api/user/protocols.py

@@ -0,0 +1,11 @@
+from typing import Protocol
+
+from deepset_mcp.api.shared_models import DeepsetUser
+
+
+class UserResourceProtocol(Protocol):
+    """Protocol defining the implementation for UserResource."""
+
+    async def get(self, user_id: str) -> DeepsetUser:
+        """Get user information by user ID."""
+        ...

deepset_mcp/api/user/resource.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+from deepset_mcp.api.exceptions import ResourceNotFoundError
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.shared_models import DeepsetUser
+from deepset_mcp.api.transport import raise_for_status
+from deepset_mcp.api.user.protocols import UserResourceProtocol
+
+
+class UserResource(UserResourceProtocol):
+    """Resource for managing users in deepset."""
+
+    def __init__(self, client: AsyncClientProtocol) -> None:
+        """Initialize a UserResource.
+
+        :param client: The API client to use for requests.
+        """
+        self._client = client
+
+    async def get(self, user_id: str) -> DeepsetUser:
+        """Get user information by user ID.
+
+        :param user_id: The ID of the user to fetch.
+
+        :returns: User information.
+        """
+        resp = await self._client.request(
+            endpoint=f"v1/users/{user_id}",
+            method="GET",
+            response_type=dict[str, Any],
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is None:
+            raise ResourceNotFoundError(f"User '{user_id}' not found.")
+
+        return DeepsetUser(**resp.json)

deepset_mcp/api/workspace/__init__.py

@@ -0,0 +1,7 @@
+"""Workspace API module."""
+
+from .models import Workspace, WorkspaceList
+from .protocols import WorkspaceResourceProtocol
+from .resource import WorkspaceResource
+
+__all__ = ["Workspace", "WorkspaceList", "WorkspaceResourceProtocol", "WorkspaceResource"]

deepset_mcp/api/workspace/models.py

@@ -0,0 +1,23 @@
+"""Models for workspace API responses."""
+
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class Workspace(BaseModel):
+    """Model representing a workspace on the deepset platform."""
+
+    name: str
+    workspace_id: UUID
+    languages: dict[str, Any]
+    default_idle_timeout_in_seconds: int
+
+
+class WorkspaceList(BaseModel):
+    """Model representing a list of workspaces."""
+
+    data: list[Workspace]
+    has_more: bool = False
+    total: int

deepset_mcp/api/workspace/protocols.py

@@ -0,0 +1,41 @@
+"""Protocols for workspace resources."""
+
+from typing import Protocol
+
+from deepset_mcp.api.shared_models import NoContentResponse
+from deepset_mcp.api.workspace.models import Workspace, WorkspaceList
+
+
+class WorkspaceResourceProtocol(Protocol):
+    """Protocol defining the interface for workspace resources."""
+
+    async def list(self) -> WorkspaceList:
+        """List all workspaces.
+
+        :returns: A WorkspaceList containing all workspaces.
+        """
+        ...
+
+    async def get(self, workspace_name: str) -> Workspace:
+        """Get a specific workspace by name.
+
+        :param workspace_name: Name of the workspace to fetch.
+        :returns: A Workspace instance.
+        """
+        ...
+
+    async def create(self, name: str) -> NoContentResponse:
+        """Create a new workspace.
+
+        :param name: Name of the new workspace.
+        :returns: NoContentResponse indicating successful creation.
+        """
+        ...
+
+    async def delete(self, workspace_name: str) -> NoContentResponse:
+        """Delete a workspace.
+
+        :param workspace_name: Name of the workspace to delete.
+        :returns: NoContentResponse indicating successful deletion.
+        """
+        ...