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

deepset_mcp/api/indexes/resource.py

@@ -2,11 +2,15 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from typing import Any
+from urllib.parse import quote
+
 from deepset_mcp.api.exceptions import UnexpectedAPIError
-from deepset_mcp.api.indexes.models import Index, IndexList
+from deepset_mcp.api.indexes.models import Index
 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.shared_models import PaginatedResponse
 from deepset_mcp.api.transport import raise_for_status
 
 
@@ -22,24 +26,45 @@ class IndexResource(IndexResourceProtocol):
         self._client = client
         self._workspace = workspace
 
-    async def list(self, limit: int = 10, page_number: int = 1) -> IndexList:
-        """List all indexes.
+    async def list(self, limit: int = 10, after: str | None = None) -> PaginatedResponse[Index]:
+        """Lists indexes and returns the first page of results.
 
-        :param limit: Maximum number of indexes to return.
-        :param page_number: Page number for pagination.
+        The returned object can be iterated over to fetch subsequent pages.
 
-        :returns: List of indexes.
+        :param limit: The maximum number of indexes to return per page.
+        :param after: The cursor to fetch the next page of results.
+        :returns: A `PaginatedResponse` object containing the first page of indexes.
         """
-        params = {
-            "limit": limit,
-            "page_number": page_number,
-        }
-
-        response = await self._client.request(f"/v1/workspaces/{self._workspace}/indexes", params=params)
+        # 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 indexes older than the current cursor
+        # TODO: while 'before' signals indexes 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, "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},
+        )
+        return page
 
-        raise_for_status(response)
+    async def _list_api_call(self, **kwargs: Any) -> PaginatedResponse[Index]:
+        """A private, stateless method that performs the raw API call."""
+        resp = await self._client.request(
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/indexes", method="GET", params=kwargs
+        )
+        raise_for_status(resp)
+        if resp.json is None:
+            raise UnexpectedAPIError(status_code=resp.status_code, message="Empty response", detail=None)
 
-        return IndexList.model_validate(response.json)
+        return PaginatedResponse[Index].create_with_cursor_field(resp.json, "pipeline_index_id")
 
     async def get(self, index_name: str) -> Index:
         """Get a specific index.
@@ -48,28 +73,32 @@ class IndexResource(IndexResourceProtocol):
 
         :returns: Index details.
         """
-        response = await self._client.request(f"/v1/workspaces/{self._workspace}/indexes/{index_name}")
+        response = await self._client.request(
+            f"/v1/workspaces/{quote(self._workspace, safe='')}/indexes/{quote(index_name, safe='')}"
+        )
 
         raise_for_status(response)
 
         return Index.model_validate(response.json)
 
-    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
         """
         data = {
-            "name": name,
+            "name": index_name,
             "config_yaml": yaml_config,
         }
         if description is not None:
             data["description"] = description
 
-        response = await self._client.request(f"v1/workspaces/{self._workspace}/indexes", method="POST", data=data)
+        response = await self._client.request(
+            f"v1/workspaces/{quote(self._workspace, safe='')}/indexes", method="POST", data=data
+        )
 
         raise_for_status(response)
 
@@ -95,7 +124,9 @@ class IndexResource(IndexResourceProtocol):
             raise ValueError("At least one of updated_index_name or yaml_config must be provided")
 
         response = await self._client.request(
-            f"/v1/workspaces/{self._workspace}/indexes/{index_name}", method="PATCH", data=data
+            f"/v1/workspaces/{quote(self._workspace, safe='')}/indexes/{quote(index_name, safe='')}",
+            method="PATCH",
+            data=data,
         )
 
         raise_for_status(response)
@@ -107,7 +138,9 @@ class IndexResource(IndexResourceProtocol):
 
         :param index_name: Name of the index to delete.
         """
-        response = await self._client.request(f"/v1/workspaces/{self._workspace}/indexes/{index_name}", method="DELETE")
+        response = await self._client.request(
+            f"/v1/workspaces/{quote(self._workspace, safe='')}/indexes/{quote(index_name, safe='')}", method="DELETE"
+        )
 
         raise_for_status(response)
 
@@ -119,7 +152,7 @@ class IndexResource(IndexResourceProtocol):
         :raises UnexpectedAPIError: If the API returns an unexpected status code.
         """
         resp = await self._client.request(
-            endpoint=f"v1/workspaces/{self._workspace}/indexes/{index_name}/deploy",
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/indexes/{quote(index_name, safe='')}/deploy",
             method="POST",
         )
 
@@ -140,3 +173,34 @@ class IndexResource(IndexResourceProtocol):
             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)

deepset_mcp/api/integrations/__init__.py

@@ -3,3 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 """Integration API resources and models."""
+
+from .resource import IntegrationResource
+
+__all__ = ["IntegrationResource"]

deepset_mcp/api/integrations/models.py

@@ -35,19 +35,10 @@ class Integration(BaseModel):
     """Model representing an integration."""
 
     invalid: bool
+    "Whether the integration configuration is invalid or misconfigured"
     model_registry_token_id: UUID
+    "Unique identifier for the model registry token"
     provider: IntegrationProvider
+    "The integration provider type (e.g., OpenAI, Azure, etc.)"
     provider_domain: str
-
-
-class IntegrationList(BaseModel):
-    """Model representing a list of integrations."""
-
-    integrations: list[Integration]
-
-    def __len__(self) -> int:
-        """Return the length of the list.
-
-        :returns: Number of integrations.
-        """
-        return len(self.integrations)
+    "Domain or endpoint URL for the integration provider"

deepset_mcp/api/integrations/protocols.py

@@ -6,7 +6,7 @@
 
 from typing import TYPE_CHECKING, Protocol
 
-from deepset_mcp.api.integrations.models import Integration, IntegrationList, IntegrationProvider
+from deepset_mcp.api.integrations.models import Integration, IntegrationProvider
 
 if TYPE_CHECKING:
     pass
@@ -15,10 +15,10 @@ if TYPE_CHECKING:
 class IntegrationResourceProtocol(Protocol):
     """Protocol for integration resource operations."""
 
-    async def list(self) -> IntegrationList:
+    async def list(self) -> list[Integration]:
         """Retrieve all integrations.
 
-        :returns: IntegrationList containing all available integrations.
+        :returns: list containing all available integrations.
         """
         ...
 

deepset_mcp/api/integrations/resource.py

@@ -7,7 +7,7 @@
 import logging
 from typing import TYPE_CHECKING
 
-from deepset_mcp.api.integrations.models import Integration, IntegrationList, IntegrationProvider
+from deepset_mcp.api.integrations.models import Integration, IntegrationProvider
 from deepset_mcp.api.integrations.protocols import IntegrationResourceProtocol
 from deepset_mcp.api.transport import raise_for_status
 
@@ -27,10 +27,10 @@ class IntegrationResource(IntegrationResourceProtocol):
         """
         self._client = client
 
-    async def list(self) -> IntegrationList:
+    async def list(self) -> list[Integration]:
         """Retrieve all integrations.
 
-        :returns: IntegrationList containing all available integrations.
+        :returns: list containing all available integrations.
         """
         resp = await self._client.request(
             endpoint="v1/model_registry_tokens",
@@ -41,9 +41,9 @@ class IntegrationResource(IntegrationResourceProtocol):
 
         if resp.json is not None:
             integrations = [Integration.model_validate(item) for item in resp.json]
-            return IntegrationList(integrations=integrations)
+            return integrations
         else:
-            return IntegrationList(integrations=[])
+            return []
 
     async def get(self, provider: IntegrationProvider) -> Integration:
         """Retrieve a specific integration by provider.

deepset_mcp/api/pipeline/__init__.py

@@ -2,20 +2,6 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from .models import (
-    DeepsetPipeline,
-    PipelineLog,
-    PipelineLogList,
-    PipelineValidationResult,
-    ValidationError,
-)
 from .resource import PipelineResource
 
-__all__ = [
-    "DeepsetPipeline",
-    "PipelineValidationResult",
-    "ValidationError",
-    "PipelineResource",
-    "PipelineLog",
-    "PipelineLogList",
-]
+__all__ = ["PipelineResource"]

deepset_mcp/api/pipeline/models.py

@@ -25,17 +25,26 @@ class DeepsetPipeline(BaseModel):
     """Model representing a pipeline on the deepset platform."""
 
     id: str = Field(alias="pipeline_id")
+    "Unique identifier for the pipeline"
     name: str
+    "Human-readable name of the pipeline"
     status: str
+    "Current operational status of the pipeline"
     service_level: PipelineServiceLevel
+    "Service level indicating the deployment stage"
 
     created_at: datetime
+    "Timestamp when the pipeline was created"
     last_updated_at: datetime | None = Field(None, alias="last_edited_at")  # Map API's last_edited_at
+    "Timestamp when the pipeline was last modified"
 
     created_by: DeepsetUser
+    "User who created the pipeline"
     last_updated_by: DeepsetUser | None = Field(None, alias="last_edited_by")  # Map API's last_edited_by
+    "User who last modified the pipeline"
 
     yaml_config: str | None = None
+    "YAML configuration defining the pipeline structure"
 
     class Config:
         """Configuration for serialization and deserialization."""
@@ -67,14 +76,18 @@ class ValidationError(BaseModel):
     """Model representing a validation error from the pipeline validation API."""
 
     code: str
+    "Error code identifying the type of validation error"
     message: str
+    "Human-readable description of the validation error"
 
 
 class PipelineValidationResult(BaseModel):
     """Result of validating a pipeline configuration."""
 
     valid: bool
+    "Whether the pipeline configuration is valid"
     errors: list[ValidationError] = []
+    "List of validation errors if the pipeline is invalid"
 
     def __rich_repr__(self) -> Result:
         """Used to display the model in an LLM friendly way."""
@@ -86,36 +99,41 @@ class TraceFrame(BaseModel):
     """Model representing a single frame in a stack trace."""
 
     filename: str
+    "Name of the file where the trace frame occurred"
     line_number: int
+    "Line number in the file where the trace frame occurred"
     name: str
+    "Function or method name where the trace frame occurred"
 
 
 class ExceptionInfo(BaseModel):
     """Model representing exception information."""
 
     type: str
+    "Exception class name"
     value: str
+    "Exception message or string representation"
     trace: list[TraceFrame]
+    "Stack trace frames leading to the exception"
 
 
 class PipelineLog(BaseModel):
     """Model representing a single log entry from a pipeline."""
 
     log_id: str
+    "Unique identifier for the log entry"
     message: str
+    "Log message content"
     logged_at: datetime
+    "Timestamp when the log entry was created"
     level: str
+    "Log level (e.g., INFO, WARNING, ERROR)"
     origin: str
+    "Source component or service that generated the log"
     exceptions: list[ExceptionInfo] | None = None
+    "Exception information if the log contains error details"
     extra_fields: dict[str, Any] = Field(default_factory=dict)
-
-
-class PipelineLogList(BaseModel):
-    """Model representing a paginated list of pipeline logs."""
-
-    data: list[PipelineLog]
-    has_more: bool
-    total: int
+    "Additional metadata fields associated with the log entry"
 
 
 # Search-related models
@@ -125,48 +143,76 @@ class OffsetRange(BaseModel):
     """Model representing an offset range."""
 
     start: int
+    "Starting position of the offset range"
     end: int
+    "Ending position of the offset range"
 
 
 class DeepsetAnswer(BaseModel):
     """Model representing a search answer."""
 
     answer: str  # Required field
+    "The generated answer text"
     context: str | None = None
+    "Context text used to generate the answer"
     document_id: str | None = None
+    "Identifier of the source document"
     document_ids: list[str] | None = None
+    "List of source document identifiers"
     file: dict[str, Any] | None = None
+    "File metadata associated with the answer"
     files: list[dict[str, Any]] | None = None
+    "List of file metadata associated with the answer"
     meta: dict[str, Any] | None = None
+    "Additional metadata about the answer"
     offsets_in_context: list[OffsetRange] | None = None
+    "Character offset ranges within the context text"
     offsets_in_document: list[OffsetRange] | None = None
+    "Character offset ranges within the source document"
     prompt: str | None = None
+    "Prompt used to generate the answer"
     result_id: UUID | None = None
+    "Unique identifier for this result"
     score: float | None = None
+    "Confidence or relevance score for the answer"
     type: str | None = None
+    "Type classification of the answer"
 
 
 class DeepsetDocument(BaseModel):
     """Model representing a search document."""
 
     content: str  # Required field
+    "Text content of the document"
     meta: dict[str, Any]  # Required field - can hold any value
+    "Metadata dictionary containing document properties"
     embedding: list[float] | None = None
+    "Vector embedding representation of the document"
     file: dict[str, Any] | None = None
+    "File metadata if the document originated from a file"
     id: str | None = None
+    "Unique identifier for the document"
     result_id: UUID | None = None
+    "Unique identifier for this search result"
     score: float | None = None
+    "Relevance or similarity score for the document"
 
 
 class DeepsetSearchResponse(BaseModel):
     """Model representing a single search result."""
 
     debug: dict[str, Any] | None = Field(default=None, alias="_debug")
+    "Debug information for the search operation"
     answers: list[DeepsetAnswer] = Field(default_factory=list)
+    "List of generated answers from the search"
     documents: list[DeepsetDocument] = Field(default_factory=list)
+    "List of retrieved documents from the search"
     prompts: dict[str, str] | None = None
+    "Prompts used during the search operation"
     query: str | None = None
+    "Original search query text"
     query_id: UUID | None = None
+    "Unique identifier for the search query"
 
     @model_validator(mode="before")
     @classmethod
@@ -203,37 +249,29 @@ class StreamDelta(BaseModel):
     """Model representing a streaming delta."""
 
     text: str
+    "Incremental text content for streaming responses"
     meta: dict[str, Any] | None = None
+    "Metadata associated with the streaming delta"
 
 
 class DeepsetStreamEvent(BaseModel):
     """Model representing a stream event."""
 
     query_id: str | UUID | None = None
+    "Unique identifier for the associated query"
     type: str  # "delta", "result", or "error"
+    "Event type: 'delta', 'result', or 'error'"
     delta: StreamDelta | None = None
+    "Streaming text delta if type is 'delta'"
     result: DeepsetSearchResponse | None = None
+    "Complete search result if type is 'result'"
     error: str | None = None
+    "Error message if type is 'error'"
 
 
-class PipelineList(BaseModel):
-    """Response model for listing pipelines."""
-
-    data: list[DeepsetPipeline]
-    has_more: bool
-    total: int
-
+class LogLevel(StrEnum):
+    """Log level filter options for pipeline logs."""
 
-class PipelineValidationResultWithYaml(BaseModel):
-    """Model for pipeline validation result that includes the original YAML."""
-
-    validation_result: PipelineValidationResult
-    yaml_config: str
-
-
-class PipelineOperationWithErrors(BaseModel):
-    """Model for pipeline operations that complete with validation errors."""
-
-    message: str
-    validation_result: PipelineValidationResult
-    pipeline: DeepsetPipeline
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"

deepset_mcp/api/pipeline/protocols.py

@@ -5,16 +5,15 @@
 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,
+    LogLevel,
+    PipelineLog,
     PipelineValidationResult,
 )
-from deepset_mcp.api.shared_models import NoContentResponse
+from deepset_mcp.api.shared_models import NoContentResponse, PaginatedResponse
 
 
 class PipelineResourceProtocol(Protocol):
@@ -28,11 +27,7 @@ class PipelineResourceProtocol(Protocol):
         """Fetch a single pipeline by its name."""
         ...
 
-    async def list(
-        self,
-        page_number: int = 1,
-        limit: int = 10,
-    ) -> PipelineList:
+    async def list(self, limit: int = 10, after: str | None = None) -> PaginatedResponse[DeepsetPipeline]:
         """List pipelines in the configured workspace with optional pagination."""
         ...
 
@@ -54,7 +49,8 @@ class PipelineResourceProtocol(Protocol):
         pipeline_name: str,
         limit: int = 30,
         level: LogLevel | None = None,
-    ) -> PipelineLogList:
+        after: str | None = None,
+    ) -> PaginatedResponse[PipelineLog]:
         """Fetch logs for a specific pipeline."""
         ...