deepset-mcp 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

deepset_mcp/__init__.py

@@ -3,8 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from deepset_mcp.config import DEEPSET_DOCS_DEFAULT_SHARE_URL
-from deepset_mcp.server import configure_mcp_server
-from deepset_mcp.tool_models import WorkspaceMode
-from deepset_mcp.tool_registry import ALL_DEEPSET_TOOLS
+from deepset_mcp.mcp.server import configure_mcp_server
+from deepset_mcp.mcp.tool_registry import ALL_DEEPSET_TOOLS
 
-__all__ = ["configure_mcp_server", "WorkspaceMode", "ALL_DEEPSET_TOOLS", "DEEPSET_DOCS_DEFAULT_SHARE_URL"]
+__all__ = ["configure_mcp_server", "ALL_DEEPSET_TOOLS", "DEEPSET_DOCS_DEFAULT_SHARE_URL"]

deepset_mcp/api/__init__.py

@@ -2,3 +2,6 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from .client import AsyncDeepsetClient
+
+__all__ = ["AsyncDeepsetClient"]

deepset_mcp/api/client.py

@@ -29,7 +29,27 @@ T = TypeVar("T")
 
 
 class AsyncDeepsetClient(AsyncClientProtocol):
-    """Async Client for interacting with the deepset API."""
+    """Async Client for interacting with the deepset API.
+
+    This client provides asynchronous access to most deepset API endpoints
+    and resources through a convenient interface.
+
+    **Example usage:**
+
+    ```python
+    from deepset_mcp.api import AsyncDeepsetClient
+
+    async with AsyncDeepsetClient() as client:
+        pipes = await client.pipelines(workspace="example-workspace")
+        all_pipelines = await pipes.list()
+        example_pipeline = await pipes.get(pipeline_name="example-pipeline")
+        await pipes.create(pipeline_name="example-pipeline-v2", yaml_config="...")
+
+        indexes = await client.indexes(workspace="example-workspace")
+        all_indexes = await indexes.list()
+        example_index = await indexes.get(index_name="example-index")
+    ```
+    """
 
     def __init__(
         self,
@@ -38,19 +58,13 @@ class AsyncDeepsetClient(AsyncClientProtocol):
         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).
+        """Initialize an instance of the AsyncDeepsetClient.
+
+        :param api_key: API key or token. Falls back to DEEPSET_API_KEY env var
+        :param base_url: Base URL for the deepset API
+        :param transport: Custom transport implementation
+        :param transport_config: Configuration for default transport (e.g. timeout). All configuration parameters are
+            forwarded to httpx.AsyncClient.
         """
         self.api_key = api_key or os.environ.get("DEEPSET_API_KEY")
         if not self.api_key:
@@ -65,6 +79,73 @@ class AsyncDeepsetClient(AsyncClientProtocol):
                 config=transport_config,
             )
 
+    def pipelines(self, workspace: str) -> PipelineResource:
+        """Resource to interact with pipelines in the specified workspace.
+
+        :param workspace: Workspace identifier
+        :returns: Pipeline resource instance
+        """
+        return PipelineResource(client=self, workspace=workspace)
+
+    def indexes(self, workspace: str) -> IndexResource:
+        """Resource to interact with indexes in the specified workspace.
+
+        :param workspace: Workspace identifier
+        :returns: Index resource instance
+        """
+        return IndexResource(client=self, workspace=workspace)
+
+    def pipeline_templates(self, workspace: str) -> PipelineTemplateResource:
+        """Resource to interact with pipeline templates in the specified workspace.
+
+        :param workspace: Workspace identifier
+        :returns: Pipeline template resource instance
+        """
+        return PipelineTemplateResource(client=self, workspace=workspace)
+
+    def haystack_service(self) -> HaystackServiceResource:
+        """Resource to interact with the Haystack service API.
+
+        :returns: Haystack service resource instance
+        """
+        return HaystackServiceResource(client=self)
+
+    def integrations(self) -> IntegrationResource:
+        """Resource to interact with integrations.
+
+        :returns: Integration resource instance
+        """
+        return IntegrationResource(client=self)
+
+    def custom_components(self, workspace: str) -> CustomComponentsResource:
+        """Resource to interact with custom components in the specified workspace.
+
+        :param workspace: Workspace identifier
+        :returns: Custom components resource instance
+        """
+        return CustomComponentsResource(client=self)
+
+    def secrets(self) -> SecretResource:
+        """Resource to interact with secrets.
+
+        :returns: Secret resource instance
+        """
+        return SecretResource(client=self)
+
+    def workspaces(self) -> WorkspaceResource:
+        """Resource to interact with workspaces.
+
+        :returns: Workspace resource instance
+        """
+        return WorkspaceResource(client=self)
+
+    def users(self) -> UserResource:
+        """Resource to interact with users.
+
+        :returns: User resource instance
+        """
+        return UserResource(client=self)
+
     @overload
     async def request(
         self,
@@ -102,31 +183,17 @@ class AsyncDeepsetClient(AsyncClientProtocol):
         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
+        """Make a regular (non-streaming) request to the deepset API.
+
+        :param endpoint: API endpoint path
+        :param method: HTTP method
+        :param data: JSON data to send in request body
+        :param headers: Additional headers to include
+        :param response_type: Expected response type for type checking
+        :param timeout: Request timeout in seconds. If "config", uses transport config timeout.
+            If None, disables timeout. If float, uses specific timeout
+        :param kwargs: Additional arguments to pass to transport
+        :returns: Response with parsed JSON if available
         """
         if not endpoint.startswith("/"):
             endpoint = f"/{endpoint}"
@@ -163,41 +230,29 @@ class AsyncDeepsetClient(AsyncClientProtocol):
         headers: dict[str, str] | None = None,
         **kwargs: Any,
     ) -> AbstractAsyncContextManager[StreamingResponse]:
-        """
-        Make a streaming request to the deepset API.
+        """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}")
+        Example::
+
+            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}")
+
+        :param endpoint: API endpoint path
+        :param method: HTTP method (usually POST for streaming)
+        :param data: JSON data to send in request body
+        :param headers: Additional headers to include
+        :param kwargs: Additional arguments to pass to transport
+        :returns: Response object with streaming capabilities
         """
 
         @asynccontextmanager
@@ -243,39 +298,3 @@ class AsyncDeepsetClient(AsyncClientProtocol):
         """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/__init__.py

@@ -2,3 +2,6 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from .resource import CustomComponentsResource
+
+__all__ = ["CustomComponentsResource"]

deepset_mcp/api/custom_components/models.py

@@ -13,17 +13,16 @@ class CustomComponentInstallation(BaseModel):
     """Model representing a custom component installation."""
 
     custom_component_id: str
+    "Unique identifier for the custom component"
     status: str
+    "Current installation status of the component"
     version: str
+    "Version number of the installed component"
     created_by_user_id: str
+    "ID of the user who initiated the installation"
     logs: list[dict[str, Any]]
+    "Installation log entries with timestamps and messages"
     organization_id: str
+    "ID of the organization where the component is installed"
     user_info: DeepsetUser | None = None
-
-
-class CustomComponentInstallationList(BaseModel):
-    """Model representing a list of custom component installations."""
-
-    data: list[CustomComponentInstallation]
-    total: int
-    has_more: bool
+    "Detailed information about the user who created the installation"

deepset_mcp/api/custom_components/protocols.py

@@ -4,15 +4,16 @@
 
 from typing import Protocol
 
-from deepset_mcp.api.custom_components.models import CustomComponentInstallationList
+from deepset_mcp.api.custom_components.models import CustomComponentInstallation
+from deepset_mcp.api.shared_models import PaginatedResponse
 
 
 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:
+        self, limit: int = 20, after: str | None = None, field: str = "created_at", order: str = "DESC"
+    ) -> PaginatedResponse[CustomComponentInstallation]:
         """List custom component installations."""
         ...
 

deepset_mcp/api/custom_components/resource.py

@@ -3,10 +3,13 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from typing import Any
+from urllib.parse import quote
 
-from deepset_mcp.api.custom_components.models import CustomComponentInstallationList
+from deepset_mcp.api.custom_components.models import CustomComponentInstallation
 from deepset_mcp.api.custom_components.protocols import CustomComponentsProtocol
+from deepset_mcp.api.exceptions import UnexpectedAPIError
 from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.shared_models import PaginatedResponse
 from deepset_mcp.api.transport import raise_for_status
 
 
@@ -21,29 +24,52 @@ class CustomComponentsResource(CustomComponentsProtocol):
         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.
+        self, limit: int = 20, after: str | None = None, field: str = "created_at", order: str = "DESC"
+    ) -> PaginatedResponse[CustomComponentInstallation]:
+        """Lists custom component installations and returns the first page of results.
 
-        :param limit: Maximum number of installations to return.
-        :param page_number: Page number for pagination.
+        The returned object can be iterated over to fetch subsequent pages.
+
+        :param limit: Maximum number of installations to return per page.
+        :param after: The cursor to fetch the next page of results.
         :param field: Field to sort by.
         :param order: Sort order (ASC or DESC).
-
-        :returns: List of custom component installations.
+        :returns: A `PaginatedResponse` object containing the first page of installations.
         """
+        # 1. Prepare arguments for the initial API call
+        # TODO: Pagination in the deepset API is currently implemented in an unintuitive way.
+        # TODO: The cursor is always time based (created_at) and after signifies installations older than the
+        # TODO: current cursor
+        # TODO: while 'before' signals installations younger than the current cursor.
+        # TODO: This is applied irrespective of any sort (e.g. name) that would conflict with this approach.
+        # TODO: Change this to 'after' once the behaviour is fixed on the deepset API
+        request_params = {"limit": limit, "field": field, "order": order, "before": after}
+        request_params = {k: v for k, v in request_params.items() if v is not None}
+
+        # 2. Make the first API call using a private, stateless method
+        page = await self._list_api_call(**request_params)
+
+        # 3. Inject the logic needed for subsequent fetches into the response object
+        page._inject_paginator(
+            fetch_func=self._list_api_call,
+            # Base args for the *next* fetch don't include initial cursors
+            base_args={"limit": limit, "field": field, "order": order},
+        )
+        return page
+
+    async def _list_api_call(self, **kwargs: Any) -> PaginatedResponse[CustomComponentInstallation]:
+        """A private, stateless method that performs the raw API call."""
+        params = "&".join([f"{key}={quote(str(value), safe='')}" for key, value in kwargs.items()])
         resp = await self._client.request(
-            endpoint=f"v2/custom_components?limit={limit}&page_number={page_number}&field={field}&order={order}",
+            endpoint=f"v2/custom_components?{params}",
             method="GET",
             response_type=dict[str, Any],
         )
-
         raise_for_status(resp)
-
         if resp.json is None:
-            return CustomComponentInstallationList(data=[], total=0, has_more=False)
+            raise UnexpectedAPIError(status_code=resp.status_code, message="Empty response", detail=None)
 
-        return CustomComponentInstallationList(**resp.json)
+        return PaginatedResponse[CustomComponentInstallation].create_with_cursor_field(resp.json, "custom_component_id")
 
     async def get_latest_installation_logs(self) -> str | None:
         """Get the logs from the latest custom component installation.

deepset_mcp/api/haystack_service/__init__.py

@@ -2,3 +2,6 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from .resource import HaystackServiceResource
+
+__all__ = ["HaystackServiceResource"]

deepset_mcp/api/haystack_service/protocols.py

@@ -15,3 +15,24 @@ class HaystackServiceProtocol(Protocol):
     async def get_component_input_output(self, component_name: str) -> dict[str, Any]:
         """Fetch input and output schema for a component from the API."""
         ...
+
+    async def run_component(
+        self,
+        component_type: str,
+        init_params: dict[str, Any] | None = None,
+        input_data: dict[str, Any] | None = None,
+        input_types: dict[str, str] | None = None,
+        workspace: str | None = None,
+    ) -> dict[str, Any]:
+        """Run a Haystack component with the given parameters.
+
+        :param component_type: The type of component to run
+            (e.g., "haystack.components.builders.prompt_builder.PromptBuilder")
+        :param init_params: Initialization parameters for the component
+        :param input_data: Input data for the component
+        :param input_types: Optional type information for inputs (inferred if not provided)
+        :param workspace: Optional workspace name to run the component in
+
+        :returns: Dictionary containing the component's output sockets
+        """
+        ...

deepset_mcp/api/haystack_service/resource.py

@@ -57,3 +57,49 @@ class HaystackServiceResource(HaystackServiceProtocol):
             raise ResourceNotFoundError(f"Component '{component_name}' not found.")
 
         return resp.json[0] if resp.json is not None else {}
+
+    async def run_component(
+        self,
+        component_type: str,
+        init_params: dict[str, Any] | None = None,
+        input_data: dict[str, Any] | None = None,
+        input_types: dict[str, str] | None = None,
+        workspace: str | None = None,
+    ) -> dict[str, Any]:
+        """Run a Haystack component with the given parameters.
+
+        :param component_type: The type of component to run (e.g., "haystack.components.builders.PromptBuilder")
+        :param init_params: Initialization parameters for the component
+        :param input_data: Input data for the component
+        :param input_types: Optional type information for inputs (inferred if not provided)
+        :param workspace: Optional workspace name to run the component in
+
+        :returns: Dictionary containing the component's output sockets
+        """
+        payload: dict[str, Any] = {
+            "component_type": component_type,
+            "init_params": init_params or {},
+            "input": input_data or {},
+        }
+
+        if input_types is not None:
+            payload["input_types"] = input_types
+
+        endpoint = "v1/haystack/components/run"
+        if workspace is not None:
+            endpoint = f"v1/workspaces/{workspace}/haystack/components/run"
+
+        resp = await self._client.request(
+            endpoint=endpoint,
+            method="POST",
+            headers={
+                "accept": "application/json",
+                "content-type": "application/json",
+            },
+            data=payload,
+            response_type=dict[str, Any],
+        )
+
+        raise_for_status(resp)
+
+        return resp.json if resp.json is not None else {}

deepset_mcp/api/indexes/__init__.py

@@ -2,3 +2,6 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from .resource import IndexResource
+
+__all__ = ["IndexResource"]

deepset_mcp/api/indexes/models.py

@@ -5,7 +5,7 @@
 from datetime import datetime
 from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from rich.repr import Result
 
 from deepset_mcp.api.shared_models import DeepsetUser
@@ -15,30 +15,50 @@ class IndexStatus(BaseModel):
     """Status information about documents in an index."""
 
     pending_file_count: int
+    "Number of files waiting to be processed"
     failed_file_count: int
+    "Number of files that failed during indexing"
     indexed_no_documents_file_count: int
+    "Number of files indexed but containing no documents"
     indexed_file_count: int
+    "Number of successfully indexed files"
     total_file_count: int
+    "Total number of files in the index"
 
 
 class Index(BaseModel):
     """A deepset index."""
 
     pipeline_index_id: str
+    "Unique identifier for the pipeline index"
     name: str
+    "Human-readable name of the index"
     description: str | None = None
-    config_yaml: str
+    "Optional description of the index purpose and contents"
+    yaml_config: str = Field(alias="config_yaml")
+    "YAML configuration defining the index structure and settings"
     workspace_id: str
+    "ID of the workspace containing this index"
     settings: dict[str, Any]
+    "Index configuration settings and parameters"
     desired_status: str
+    "Target operational status for the index"
     deployed_at: datetime | None = None
+    "Timestamp when the index was deployed"
     last_edited_at: datetime | None = None
+    "Timestamp when the index was last modified"
     max_index_replica_count: int
+    "Maximum number of replicas allowed for this index"
     created_at: datetime
+    "Timestamp when the index was created"
     updated_at: datetime | None = None
+    "Timestamp when the index was last updated"
     created_by: DeepsetUser
+    "User who created the index"
     last_edited_by: DeepsetUser | None = None
+    "User who last modified the index"
     status: IndexStatus
+    "Current status information about documents in the index"
 
     def __rich_repr__(self) -> Result:
         """Used to display the model in an LLM friendly way."""
@@ -56,12 +76,4 @@ class Index(BaseModel):
             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
+        yield "yaml_config", self.yaml_config if self.yaml_config is not None else "Get full index to see config."

deepset_mcp/api/indexes/protocols.py

@@ -4,14 +4,15 @@
 
 from typing import Protocol
 
-from deepset_mcp.api.indexes.models import Index, IndexList
+from deepset_mcp.api.indexes.models import Index
 from deepset_mcp.api.pipeline.models import PipelineValidationResult
+from deepset_mcp.api.shared_models import PaginatedResponse
 
 
 class IndexResourceProtocol(Protocol):
     """Protocol defining the implementation for IndexResource."""
 
-    async def list(self, limit: int = 10, page_number: int = 1) -> IndexList:
+    async def list(self, limit: int = 10, after: str | None = None) -> PaginatedResponse[Index]:
         """List indexes in the configured workspace."""
         ...
 
@@ -19,10 +20,10 @@ class IndexResourceProtocol(Protocol):
         """Fetch a single index by its name."""
         ...
 
-    async def create(self, name: str, yaml_config: str, description: str | None = None) -> Index:
+    async def create(self, index_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 index_name: Name of the index
         :param yaml_config: YAML configuration for the index
         :param description: Optional description for the index
         :returns: Created index details
@@ -49,6 +50,14 @@ class IndexResourceProtocol(Protocol):
         """
         ...
 
+    async def validate(self, yaml_config: str) -> PipelineValidationResult:
+        """Validate an index's YAML configuration against the API.
+
+        :param yaml_config: The YAML configuration string to validate.
+        :returns: PipelineValidationResult containing validation status and any errors.
+        """
+        ...
+
     async def delete(self, index_name: str) -> None:
         """Delete an index.