refactor: split up protocols per resource (#122)

* refactor: split up protocols per resource

* chire: update gitignore

* chore: update gitignore

Author: mathislucka

.gitignore

@@ -14,4 +14,15 @@ wheels/
 .env
 .env.prod
 .env.dev
-.env.test
+.env.test
+
+
+agent_runs/
+
+misc.xml
+modules.xml
+profiles_settings.xml
+deepset-mcp-server.iml
+Project_Default.xml
+pyright-overrides.xml
+vcs.xml

src/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."""
+        ...

src/deepset_mcp/api/custom_components/resource.py

@@ -1,7 +1,8 @@
 from typing import Any
 
 from deepset_mcp.api.custom_components.models import CustomComponentInstallationList
-from deepset_mcp.api.protocols import AsyncClientProtocol, CustomComponentsProtocol
+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
 
 

src/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."""
+        ...

src/deepset_mcp/api/haystack_service/resource.py

@@ -1,7 +1,8 @@
 from typing import Any
 
 from deepset_mcp.api.exceptions import ResourceNotFoundError
-from deepset_mcp.api.protocols import AsyncClientProtocol, HaystackServiceProtocol
+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
 
 

src/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.
+        """
+        ...

src/deepset_mcp/api/indexes/resource.py

@@ -1,11 +1,12 @@
 from deepset_mcp.api.exceptions import UnexpectedAPIError
 from deepset_mcp.api.indexes.models import Index, IndexList
+from deepset_mcp.api.indexes.protocols import IndexResourceProtocol
 from deepset_mcp.api.pipeline.models import PipelineValidationResult, ValidationError
 from deepset_mcp.api.protocols import AsyncClientProtocol
 from deepset_mcp.api.transport import raise_for_status
 
 
-class IndexResource:
+class IndexResource(IndexResourceProtocol):
     """Resource for interacting with deepset indexes."""
 
     def __init__(self, client: AsyncClientProtocol, workspace: str) -> None:

src/deepset_mcp/api/pipeline/protocols.py

@@ -0,0 +1,83 @@
+from collections.abc import AsyncIterator
+from typing import Any, Protocol
+
+from deepset_mcp.api.pipeline.log_level import LogLevel
+from deepset_mcp.api.pipeline.models import (
+    DeepsetPipeline,
+    DeepsetSearchResponse,
+    DeepsetStreamEvent,
+    PipelineList,
+    PipelineLogList,
+    PipelineValidationResult,
+)
+from deepset_mcp.api.shared_models import NoContentResponse
+
+
+class PipelineResourceProtocol(Protocol):
+    """Protocol defining the implementation for PipelineResource."""
+
+    async def validate(self, yaml_config: str) -> PipelineValidationResult:
+        """Validate a pipeline's YAML configuration against the API."""
+        ...
+
+    async def get(self, pipeline_name: str, include_yaml: bool = True) -> DeepsetPipeline:
+        """Fetch a single pipeline by its name."""
+        ...
+
+    async def list(
+        self,
+        page_number: int = 1,
+        limit: int = 10,
+    ) -> PipelineList:
+        """List pipelines in the configured workspace with optional pagination."""
+        ...
+
+    async def create(self, name: str, yaml_config: str) -> NoContentResponse:
+        """Create a new pipeline with a name and YAML config."""
+        ...
+
+    async def update(
+        self,
+        pipeline_name: str,
+        updated_pipeline_name: str | None = None,
+        yaml_config: str | None = None,
+    ) -> NoContentResponse:
+        """Update name and/or YAML config of an existing pipeline."""
+        ...
+
+    async def get_logs(
+        self,
+        pipeline_name: str,
+        limit: int = 30,
+        level: LogLevel | None = None,
+    ) -> PipelineLogList:
+        """Fetch logs for a specific pipeline."""
+        ...
+
+    async def deploy(self, pipeline_name: str) -> PipelineValidationResult:
+        """Deploy a pipeline."""
+        ...
+
+    async def search(
+        self,
+        pipeline_name: str,
+        query: str,
+        debug: bool = False,
+        view_prompts: bool = False,
+        params: dict[str, Any] | None = None,
+        filters: dict[str, Any] | None = None,
+    ) -> DeepsetSearchResponse:
+        """Search using a pipeline."""
+        ...
+
+    def search_stream(
+        self,
+        pipeline_name: str,
+        query: str,
+        debug: bool = False,
+        view_prompts: bool = False,
+        params: dict[str, Any] | None = None,
+        filters: dict[str, Any] | None = None,
+    ) -> AsyncIterator[DeepsetStreamEvent]:
+        """Search using a pipeline with response streaming."""
+        ...

src/deepset_mcp/api/pipeline/resource.py

@@ -14,6 +14,7 @@
     PipelineValidationResult,
     ValidationError,
 )
+from deepset_mcp.api.pipeline.protocols import PipelineResourceProtocol
 from deepset_mcp.api.shared_models import NoContentResponse
 from deepset_mcp.api.transport import raise_for_status
 
@@ -23,7 +24,7 @@
     from deepset_mcp.api.protocols import AsyncClientProtocol
 
 
-class PipelineResource:
+class PipelineResource(PipelineResourceProtocol):
     """Manages interactions with the deepset pipeline API."""
 
     def __init__(

src/deepset_mcp/api/pipeline_template/protocols.py

@@ -0,0 +1,17 @@
+from typing import Protocol
+
+from deepset_mcp.api.pipeline_template.models import PipelineTemplate, PipelineTemplateList
+
+
+class PipelineTemplateResourceProtocol(Protocol):
+    """Protocol defining the implementation for PipelineTemplateResource."""
+
+    async def get_template(self, template_name: str) -> PipelineTemplate:
+        """Fetch a single pipeline template by its name."""
+        ...
+
+    async def list_templates(
+        self, limit: int = 100, field: str = "created_at", order: str = "DESC", filter: str | None = None
+    ) -> PipelineTemplateList:
+        """List pipeline templates in the configured workspace."""
+        ...