Feat/align index update w pipeline update (#197)

* feat: align update index with pipeline

* feat: add validate index

Author: mathislucka

mkdocs.yml

@@ -26,8 +26,8 @@ plugins:
             show_source: false
             show_signature_annotations: true
             show_root_heading: false
-            show_root_full_path: false        # Don't show full module paths
-            show_root_members_full_path: false # Don't show full paths for members
+            show_root_full_path: true        # Don't show full module paths
+            show_root_members_full_path: true # Don't show full paths for members
             show_root_toc_entry: false
             separate_signature: true  # ← Separates signature from docstring
             signature_crossrefs: true

src/deepset_mcp/api/indexes/protocols.py

@@ -50,6 +50,14 @@ async def deploy(self, index_name: str) -> PipelineValidationResult:
         """
         ...
 
+    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.
 

src/deepset_mcp/api/indexes/resource.py

@@ -173,3 +173,34 @@ async def deploy(self, index_name: str) -> PipelineValidationResult:
             return PipelineValidationResult(valid=False, errors=errors)
 
         raise UnexpectedAPIError(status_code=resp.status_code, message=resp.text, detail=resp.json)
+
+    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.
+        :raises ValueError: If the YAML is not valid (422 error) or contains syntax errors.
+        """
+        data = {"indexing_yaml": yaml_config}
+
+        resp = await self._client.request(
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/pipeline_validations",
+            method="POST",
+            data=data,
+        )
+
+        # If successful (status 200), the YAML is valid
+        if resp.success:
+            return PipelineValidationResult(valid=True)
+
+        if resp.status_code == 400 and resp.json is not None and isinstance(resp.json, dict) and "details" in resp.json:
+            errors = [ValidationError(code=error["code"], message=error["message"]) for error in resp.json["details"]]
+
+            return PipelineValidationResult(valid=False, errors=errors)
+
+        if resp.status_code == 422:
+            errors = [ValidationError(code="YAML_ERROR", message="Syntax error in YAML")]
+
+            return PipelineValidationResult(valid=False, errors=errors)
+
+        raise UnexpectedAPIError(status_code=resp.status_code, message=resp.text, detail=resp.json)

src/deepset_mcp/mcp/tool_registry.py

@@ -27,6 +27,7 @@
     get_index as get_index_tool,
     list_indexes as list_indexes_tool,
     update_index as update_index_tool,
+    validate_index as validate_index_tool,
 )
 from deepset_mcp.tools.object_store import create_get_from_object_store, create_get_slice_from_object_store
 from deepset_mcp.tools.pipeline import (
@@ -147,6 +148,10 @@ async def search_docs(query: str) -> str:
         deploy_index_tool,
         ToolConfig(needs_client=True, needs_workspace=True, memory_type=MemoryType.EXPLORABLE),
     ),
+    "validate_index": (
+        validate_index_tool,
+        ToolConfig(needs_client=True, needs_workspace=True, memory_type=MemoryType.EXPLORABLE_AND_REFERENCEABLE),
+    ),
     "list_templates": (
         list_pipeline_templates_tool,
         ToolConfig(

src/deepset_mcp/tools/__init__.py

@@ -11,7 +11,7 @@
     run_component,
     search_component_definition,
 )
-from .indexes import create_index, deploy_index, get_index, list_indexes, update_index
+from .indexes import create_index, deploy_index, get_index, list_indexes, update_index, validate_index
 from .object_store import create_get_from_object_store, create_get_slice_from_object_store
 from .pipeline import (
     create_pipeline,
@@ -41,6 +41,7 @@
     "update_index",
     "create_index",
     "get_index",
+    "validate_index",
     "create_get_from_object_store",
     "create_get_slice_from_object_store",
     "list_pipelines",

src/deepset_mcp/tools/indexes.py

@@ -2,13 +2,36 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import yaml
+from pydantic import BaseModel
+
 from deepset_mcp.api.exceptions import BadRequestError, ResourceNotFoundError, UnexpectedAPIError
 from deepset_mcp.api.indexes.models import Index
 from deepset_mcp.api.pipeline.models import PipelineValidationResult
 from deepset_mcp.api.protocols import AsyncClientProtocol
 from deepset_mcp.api.shared_models import PaginatedResponse
 
 
+class IndexValidationResultWithYaml(BaseModel):
+    """Model for index validation result that includes the original YAML."""
+
+    validation_result: PipelineValidationResult
+    "Result of validating the index configuration"
+    yaml_config: str
+    "Original YAML configuration that was validated"
+
+
+class IndexOperationWithErrors(BaseModel):
+    """Model for index operations that complete with validation errors."""
+
+    message: str
+    "Descriptive message about the index operation"
+    validation_result: PipelineValidationResult
+    "Validation errors encountered during the operation"
+    index: Index
+    "Index object after the operation completed"
+
+
 async def list_indexes(
     *, client: AsyncClientProtocol, workspace: str, after: str | None = None
 ) -> PaginatedResponse[Index] | str:
@@ -43,6 +66,33 @@ async def get_index(*, client: AsyncClientProtocol, workspace: str, index_name:
     return response
 
 
+async def validate_index(
+    *, client: AsyncClientProtocol, workspace: str, yaml_configuration: str
+) -> IndexValidationResultWithYaml | str:
+    """Validates the provided index YAML configuration against the deepset API.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param yaml_configuration: The YAML configuration to validate.
+    :returns: Validation result with original YAML or error message.
+    """
+    if not yaml_configuration or not yaml_configuration.strip():
+        return "You need to provide a YAML configuration to validate."
+
+    try:
+        yaml.safe_load(yaml_configuration)
+    except yaml.YAMLError as e:
+        return f"Invalid YAML provided: {e}"
+
+    try:
+        response = await client.indexes(workspace=workspace).validate(yaml_configuration)
+        return IndexValidationResultWithYaml(validation_result=response, yaml_config=yaml_configuration)
+    except ResourceNotFoundError:
+        return f"There is no workspace named '{workspace}'. Did you mean to configure it?"
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to validate index: {e}"
+
+
 async def create_index(
     *,
     client: AsyncClientProtocol,
@@ -78,35 +128,78 @@ async def update_index(
     client: AsyncClientProtocol,
     workspace: str,
     index_name: str,
-    updated_index_name: str | None = None,
-    yaml_configuration: str | None = None,
-) -> dict[str, str | Index] | str:
-    """Updates an existing index in your deepset platform workspace.
+    original_config_snippet: str,
+    replacement_config_snippet: str,
+    skip_validation_errors: bool = True,
+) -> Index | IndexOperationWithErrors | str:
+    """
+    Updates an index configuration in the specified workspace with a replacement configuration snippet.
 
-    This function can update either the name or the configuration of an existing index, or both.
-    At least one of updated_index_name or yaml_configuration must be provided.
+    This function validates the replacement configuration snippet before applying it to the index.
+    If the validation fails and skip_validation_errors is False, it returns error messages.
+    Otherwise, the replacement snippet is used to update the index's configuration.
 
-    :param client: Deepset API client to use.
-    :param workspace: Workspace in which to update the index.
-    :param index_name: Unique name of the index to update.
-    :param updated_index_name: Updated name of the index.
-    :param yaml_configuration: YAML configuration to update the index with.
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param index_name: Name of the index to update.
+    :param original_config_snippet: The configuration snippet to replace.
+    :param replacement_config_snippet: The new configuration snippet.
+    :param skip_validation_errors: If True (default), updates the index even if validation fails.
+                                  If False, stops update when validation fails.
+    :returns: Updated index or error message.
     """
-    if not updated_index_name and not yaml_configuration:
-        return "You must provide either a new name or a new configuration to update the index."
-
     try:
-        result = await client.indexes(workspace=workspace).update(
-            index_name=index_name, updated_index_name=updated_index_name, yaml_config=yaml_configuration
+        original_index = await client.indexes(workspace=workspace).get(index_name=index_name)
+    except ResourceNotFoundError:
+        return f"There is no index named '{index_name}'. Did you mean to create it?"
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to fetch index '{index_name}': {e}"
+
+    if original_index.yaml_config is None:
+        return f"The index '{index_name}' does not have a YAML configuration."
+
+    occurrences = original_index.yaml_config.count(original_config_snippet)
+
+    if occurrences == 0:
+        return f"No occurrences of the provided configuration snippet were found in the index '{index_name}'."
+
+    if occurrences > 1:
+        return (
+            f"Multiple occurrences ({occurrences}) of the provided configuration snippet were found in the index "
+            f"'{index_name}'. Specify a more precise snippet to proceed with the update."
         )
+
+    updated_yaml_configuration = original_index.yaml_config.replace(
+        original_config_snippet, replacement_config_snippet, 1
+    )
+
+    try:
+        validation_response = await client.indexes(workspace=workspace).validate(updated_yaml_configuration)
+
+        if not validation_response.valid and not skip_validation_errors:
+            error_messages = [f"{error.code}: {error.message}" for error in validation_response.errors]
+            return "Index validation failed:\n" + "\n".join(error_messages)
+
+        await client.indexes(workspace=workspace).update(index_name=index_name, yaml_config=updated_yaml_configuration)
+
+        # Get the full index after update
+        index = await client.indexes(workspace=workspace).get(index_name)
+
+        # If validation failed but we proceeded anyway, return the special model
+        if not validation_response.valid:
+            return IndexOperationWithErrors(
+                message="The operation completed with errors", validation_result=validation_response, index=index
+            )
+
+        # Otherwise return just the index
+        return index
+
     except ResourceNotFoundError:
         return f"There is no index named '{index_name}'. Did you mean to create it?"
     except BadRequestError as e:
-        return f"Failed to update index '{index_name}': {e}"
+        return f"Failed to update the index '{index_name}': {e}"
     except UnexpectedAPIError as e:
-        return f"Failed to update index '{index_name}': {e}"
-
-    return {"message": f"Index '{index_name}' updated successfully.", "index": result}
+        return f"Failed to update the index '{index_name}': {e}"
 
 
 async def deploy_index(

test/integration/test_integration_index_resource.py

@@ -405,3 +405,62 @@ async def test_deploy_nonexistent_index(
     assert isinstance(result, PipelineValidationResult)
     assert result.valid is False
     assert len(result.errors) > 0
+
+
+@pytest.mark.asyncio
+async def test_validation_valid_yaml(index_resource: IndexResource, valid_index_config: str) -> None:
+    """Test validating a valid index YAML configuration."""
+    config = json.loads(valid_index_config)
+    result = await index_resource.validate(yaml_config=config["yaml_config"])
+
+    assert result.valid is True
+    assert len(result.errors) == 0
+
+
+@pytest.mark.asyncio
+async def test_validation_invalid_yaml(
+    index_resource: IndexResource,
+) -> None:
+    """Test validating an invalid index YAML configuration."""
+    # Create an invalid YAML with missing required fields
+    invalid_yaml = """
+components:
+  document_embedder:
+    # Missing 'type' field
+    init_parameters:
+      model: intfloat/e5-base-v2
+
+inputs:
+  files:
+    - document_embedder.documents
+
+max_runs_per_component: 100
+"""
+
+    result = await index_resource.validate(yaml_config=invalid_yaml)
+
+    # Check that validation failed with errors
+    assert result.valid is False
+    assert len(result.errors) > 0
+
+    # Should have a schema error (currently returns PIPELINE_SCHEMA_ERROR for indexes too)
+    assert result.errors[0].code == "PIPELINE_SCHEMA_ERROR"
+
+
+@pytest.mark.asyncio
+async def test_validation_syntax_error(
+    index_resource: IndexResource,
+) -> None:
+    """Test validating a YAML with syntax errors."""
+    invalid_yaml_syntax = """
+components:
+  document_embedder:
+    type: haystack.components.embedders.sentence_transformers_document_embedder.SentenceTransformersDocumentEmbedder
+    init_parameters
+      model: intfloat/e5-base-v2
+"""
+
+    resp = await index_resource.validate(yaml_config=invalid_yaml_syntax)
+
+    assert resp.valid is False
+    assert resp.errors[0].code == "YAML_ERROR"