feat: adds component run method to api sdk

Author: mathislucka

src/deepset_mcp/api/haystack_service/protocols.py

@@ -15,3 +15,24 @@ async def get_component_schemas(self) -> dict[str, Any]:
     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
+        """
+        ...

src/deepset_mcp/api/haystack_service/resource.py

@@ -57,3 +57,49 @@ async def get_component_input_output(self, component_name: str) -> dict[str, Any
             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 {}

test/integration/test_integration_haystack_service_resource.py

@@ -41,3 +41,38 @@ async def test_get_component_input_output(
     assert response["name"] == "Agent"
     assert "input" in response
     assert "output" in response
+
+
+@pytest.mark.asyncio
+async def test_run_component(
+    haystack_service_resource: HaystackServiceResource,
+) -> None:
+    """Test for running a Haystack component."""
+    response = await haystack_service_resource.run_component(
+        component_type="haystack.components.builders.prompt_builder.PromptBuilder",
+        init_params={"template": "Hello, {{name}}!"},
+        input_data={"name": "deepset"},
+        input_types={"name": "str"},
+    )
+
+    assert isinstance(response, dict)
+    assert "prompt" in response
+    assert response["prompt"] == "Hello, deepset!"
+
+
+@pytest.mark.asyncio
+async def test_run_component_with_workspace(
+    haystack_service_resource: HaystackServiceResource,
+) -> None:
+    """Test for running a Haystack component in a specific workspace."""
+    response = await haystack_service_resource.run_component(
+        component_type="haystack.components.builders.prompt_builder.PromptBuilder",
+        init_params={"template": "Hello, {{name}}!"},
+        input_data={"name": "deepset"},
+        input_types={"name": "str"},
+        workspace="default",
+    )
+
+    assert isinstance(response, dict)
+    assert "prompt" in response
+    assert response["prompt"] == "Hello, deepset!"

test/unit/api/haystack_service/test_haystack_service_resource.py

@@ -60,6 +60,40 @@ def mock_io_error_response(mock_client: BaseFakeClient) -> None:
     )
 
 
+def make_component_run_response() -> dict[str, Any]:
+    return {"prompt": "Generated prompt text", "metadata": {"some_key": "some_value"}}
+
+
+@pytest.fixture
+def mock_successful_run_response(mock_client: BaseFakeClient) -> None:
+    """Configure the mock client to return a successful component run response."""
+    mock_client.responses["v1/haystack/components/run"] = TransportResponse(
+        status_code=200,
+        json=make_component_run_response(),
+        text=json.dumps(make_component_run_response()),
+    )
+
+
+@pytest.fixture
+def mock_run_error_response(mock_client: BaseFakeClient) -> None:
+    """Configure the mock client to return an error response for component run."""
+    mock_client.responses["v1/haystack/components/run"] = TransportResponse(
+        status_code=500,
+        json={"message": "Internal server error"},
+        text="Internal server error",
+    )
+
+
+@pytest.fixture
+def mock_successful_workspace_run_response(mock_client: BaseFakeClient) -> None:
+    """Configure the mock client to return a successful workspace component run response."""
+    mock_client.responses["v1/workspaces/test-workspace/haystack/components/run"] = TransportResponse(
+        status_code=200,
+        json=make_component_run_response(),
+        text=json.dumps(make_component_run_response()),
+    )
+
+
 def test_initialization(mock_client: BaseFakeClient) -> None:
     """Test HaystackServiceResource initialization."""
     resource = HaystackServiceResource(client=mock_client)
@@ -115,3 +149,143 @@ async def test_get_component_input_output_error(
     resource = HaystackServiceResource(client=mock_client)
     with pytest.raises(UnexpectedAPIError):
         await resource.get_component_input_output("Agent")
+
+
+@pytest.mark.asyncio
+async def test_run_component_success(
+    mock_client: BaseFakeClient,
+    mock_successful_run_response: None,
+) -> None:
+    """Test successful component run."""
+    resource = HaystackServiceResource(client=mock_client)
+    result = await resource.run_component(
+        component_type="haystack.components.builders.PromptBuilder",
+        init_params={"some_parameter": "some_value"},
+        input_data={"question": "What does it do"},
+        input_types={"question": "str"},
+    )
+
+    assert result == make_component_run_response()
+    request = mock_client.requests[-1]
+    assert request["method"] == "POST"
+    assert request["endpoint"] == "v1/haystack/components/run"
+    assert request["headers"] == {
+        "accept": "application/json",
+        "content-type": "application/json",
+    }
+    assert request["data"] == {
+        "component_type": "haystack.components.builders.PromptBuilder",
+        "init_params": {"some_parameter": "some_value"},
+        "input": {"question": "What does it do"},
+        "input_types": {"question": "str"},
+    }
+
+
+@pytest.mark.asyncio
+async def test_run_component_minimal_params(
+    mock_client: BaseFakeClient,
+    mock_successful_run_response: None,
+) -> None:
+    """Test component run with minimal parameters."""
+    resource = HaystackServiceResource(client=mock_client)
+    result = await resource.run_component(component_type="haystack.components.builders.PromptBuilder")
+
+    assert result == make_component_run_response()
+    request = mock_client.requests[-1]
+    assert request["method"] == "POST"
+    assert request["endpoint"] == "v1/haystack/components/run"
+    assert request["headers"] == {
+        "accept": "application/json",
+        "content-type": "application/json",
+    }
+    assert request["data"] == {
+        "component_type": "haystack.components.builders.PromptBuilder",
+        "init_params": {},
+        "input": {},
+    }
+
+
+@pytest.mark.asyncio
+async def test_run_component_without_input_types(
+    mock_client: BaseFakeClient,
+    mock_successful_run_response: None,
+) -> None:
+    """Test component run without input_types (should be inferred)."""
+    resource = HaystackServiceResource(client=mock_client)
+    result = await resource.run_component(
+        component_type="haystack.components.builders.PromptBuilder",
+        init_params={"template": "Hello {{name}}"},
+        input_data={"name": "World"},
+    )
+
+    assert result == make_component_run_response()
+    request = mock_client.requests[-1]
+    assert "input_types" not in request["data"]
+
+
+@pytest.mark.asyncio
+async def test_run_component_error(
+    mock_client: BaseFakeClient,
+    mock_run_error_response: None,
+) -> None:
+    """Test error handling in component run."""
+    resource = HaystackServiceResource(client=mock_client)
+
+    with pytest.raises(UnexpectedAPIError):
+        await resource.run_component(component_type="haystack.components.builders.PromptBuilder")
+
+
+@pytest.mark.asyncio
+async def test_run_component_with_workspace(
+    mock_client: BaseFakeClient,
+    mock_successful_workspace_run_response: None,
+) -> None:
+    """Test component run with workspace parameter."""
+    resource = HaystackServiceResource(client=mock_client)
+    result = await resource.run_component(
+        component_type="haystack.components.builders.PromptBuilder",
+        init_params={"template": "Hello {{name}}"},
+        input_data={"name": "World"},
+        workspace="test-workspace",
+    )
+
+    assert result == make_component_run_response()
+    request = mock_client.requests[-1]
+    assert request["method"] == "POST"
+    assert request["endpoint"] == "v1/workspaces/test-workspace/haystack/components/run"
+    assert request["headers"] == {
+        "accept": "application/json",
+        "content-type": "application/json",
+    }
+    assert request["data"] == {
+        "component_type": "haystack.components.builders.PromptBuilder",
+        "init_params": {"template": "Hello {{name}}"},
+        "input": {"name": "World"},
+    }
+
+
+@pytest.mark.asyncio
+async def test_run_component_with_workspace_and_input_types(
+    mock_client: BaseFakeClient,
+    mock_successful_workspace_run_response: None,
+) -> None:
+    """Test component run with workspace and input_types parameters."""
+    resource = HaystackServiceResource(client=mock_client)
+    result = await resource.run_component(
+        component_type="haystack.components.builders.PromptBuilder",
+        init_params={"template": "Hello {{name}}"},
+        input_data={"name": "World"},
+        input_types={"name": "str"},
+        workspace="test-workspace",
+    )
+
+    assert result == make_component_run_response()
+    request = mock_client.requests[-1]
+    assert request["method"] == "POST"
+    assert request["endpoint"] == "v1/workspaces/test-workspace/haystack/components/run"
+    assert request["data"] == {
+        "component_type": "haystack.components.builders.PromptBuilder",
+        "init_params": {"template": "Hello {{name}}"},
+        "input": {"name": "World"},
+        "input_types": {"name": "str"},
+    }