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

deepset_mcp/api/pipeline/resource.py

@@ -6,20 +6,20 @@ import json
 import logging
 from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
 
 from deepset_mcp.api.exceptions import UnexpectedAPIError
-from deepset_mcp.api.pipeline.log_level import LogLevel
 from deepset_mcp.api.pipeline.models import (
     DeepsetPipeline,
     DeepsetSearchResponse,
     DeepsetStreamEvent,
-    PipelineList,
-    PipelineLogList,
+    LogLevel,
+    PipelineLog,
     PipelineValidationResult,
     ValidationError,
 )
 from deepset_mcp.api.pipeline.protocols import PipelineResourceProtocol
-from deepset_mcp.api.shared_models import NoContentResponse
+from deepset_mcp.api.shared_models import NoContentResponse, PaginatedResponse
 from deepset_mcp.api.transport import raise_for_status
 
 logger = logging.getLogger(__name__)
@@ -29,7 +29,7 @@ if TYPE_CHECKING:
 
 
 class PipelineResource(PipelineResourceProtocol):
-    """Manages interactions with the deepset pipeline API."""
+    """Interact with pipelines on the deepset AI platform."""
 
     def __init__(
         self,
@@ -54,7 +54,7 @@ class PipelineResource(PipelineResourceProtocol):
         data = {"query_yaml": yaml_config}
 
         resp = await self._client.request(
-            endpoint=f"v1/workspaces/{self._workspace}/pipeline_validations",
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/pipeline_validations",
             method="POST",
             data=data,
         )
@@ -75,41 +75,45 @@ class PipelineResource(PipelineResourceProtocol):
 
         raise UnexpectedAPIError(status_code=resp.status_code, message=resp.text, detail=resp.json)
 
-    async def list(
-        self,
-        page_number: int = 1,
-        limit: int = 10,
-    ) -> PipelineList:
-        """Retrieve pipeline in the configured workspace with optional pagination.
-
-        :param page_number: Page number for paging.
-        :param limit: Max number of items to return.
-        :returns: PipelineList with pipelines and metadata.
+    async def list(self, limit: int = 10, after: str | None = None) -> PaginatedResponse[DeepsetPipeline]:
+        """Lists pipelines and returns the first page of results.
+
+        The returned object can be iterated over to fetch subsequent pages.
+
+        :param limit: The maximum number of pipelines to return per page.
+        :param after: The cursor to fetch the next page of results.
+        :returns: A `PaginatedResponse` object containing the first page of pipelines.
         """
-        params: dict[str, Any] = {
-            "page_number": page_number,
-            "limit": limit,
-        }
+        # 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 pipelines older than the current cursor
+        # TODO: while 'before' signals pipelines 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
 
+    async def _list_api_call(self, **kwargs: Any) -> PaginatedResponse[DeepsetPipeline]:
+        """A private, stateless method that performs the raw API call."""
         resp = await self._client.request(
-            endpoint=f"v1/workspaces/{self._workspace}/pipelines",
-            method="GET",
-            params=params,
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines", 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)
 
-        response = resp.json
-
-        if response is not None:
-            pipelines = [DeepsetPipeline.model_validate(item) for item in response.get("data", [])]
-            return PipelineList(
-                data=pipelines,
-                has_more=response.get("has_more", False),
-                total=response.get("total", len(pipelines)),
-            )
-        else:
-            return PipelineList(data=[], has_more=False, total=0)
+        return PaginatedResponse[DeepsetPipeline].create_with_cursor_field(resp.json, "pipeline_id")
 
     async def get(self, pipeline_name: str, include_yaml: bool = True) -> DeepsetPipeline:
         """Fetch a single pipeline by its name.
@@ -118,14 +122,18 @@ class PipelineResource(PipelineResourceProtocol):
         :param include_yaml: Whether to include YAML configuration in the response.
         :returns: DeepsetPipeline instance.
         """
-        resp = await self._client.request(endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}")
+        resp = await self._client.request(
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/{quote(pipeline_name, safe='')}"
+        )
         raise_for_status(resp)
 
         pipeline = DeepsetPipeline.model_validate(resp.json)
 
         if include_yaml:
             yaml_response = await self._client.request(
-                endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}/yaml"
+                endpoint=(
+                    f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/{quote(pipeline_name, safe='')}/yaml"
+                )
             )
 
             raise_for_status(yaml_response)
@@ -135,16 +143,16 @@ class PipelineResource(PipelineResourceProtocol):
 
         return pipeline
 
-    async def create(self, name: str, yaml_config: str) -> NoContentResponse:
+    async def create(self, pipeline_name: str, yaml_config: str) -> NoContentResponse:
         """Create a new pipeline with a name and YAML config.
 
-        :param name: Name of the new pipeline.
+        :param pipeline_name: Name of the new pipeline.
         :param yaml_config: YAML configuration for the pipeline.
         :returns: NoContentResponse indicating successful creation.
         """
-        data = {"name": name, "query_yaml": yaml_config}
+        data = {"name": pipeline_name, "query_yaml": yaml_config}
         resp = await self._client.request(
-            endpoint=f"v1/workspaces/{self._workspace}/pipelines",
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines",
             method="POST",
             data=data,
         )
@@ -170,7 +178,7 @@ class PipelineResource(PipelineResourceProtocol):
         # Handle name update first if any
         if updated_pipeline_name is not None:
             name_resp = await self._client.request(
-                endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}",
+                endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/{quote(pipeline_name, safe='')}",
                 method="PATCH",
                 data={"name": updated_pipeline_name},
             )
@@ -184,7 +192,9 @@ class PipelineResource(PipelineResourceProtocol):
 
         if yaml_config is not None:
             yaml_resp = await self._client.request(
-                endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}/yaml",
+                endpoint=(
+                    f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/{quote(pipeline_name, safe='')}/yaml"
+                ),
                 method="PUT",
                 data={"query_yaml": yaml_config},
             )
@@ -205,36 +215,62 @@ class PipelineResource(PipelineResourceProtocol):
         pipeline_name: str,
         limit: int = 30,
         level: LogLevel | None = None,
-    ) -> PipelineLogList:
-        """Fetch logs for a specific pipeline.
+        after: str | None = None,
+    ) -> PaginatedResponse[PipelineLog]:
+        """Fetch logs for a specific pipeline and returns the first page of results.
+
+        The returned object can be iterated over to fetch subsequent pages.
 
         :param pipeline_name: Name of the pipeline to fetch logs for.
-        :param limit: Maximum number of log entries to return.
+        :param limit: Maximum number of log entries to return per page.
         :param level: Filter logs by level. If None, returns all levels.
-        :returns: A PipelineLogList containing the log entries.
+        :param after: The cursor to fetch the next page of results.
+        :returns: A `PaginatedResponse` object containing the first page of logs.
         """
-        params: dict[str, Any] = {
+        # 1. Prepare arguments for the initial API call
+        request_params = {
             "limit": limit,
             "filter": "origin eq 'querypipeline'",
         }
 
         # Add level filter if specified
         if level is not None:
-            params["filter"] = f"level eq '{level}' and origin eq 'querypipeline'"
+            request_params["filter"] = f"level eq '{level}' and origin eq 'querypipeline'"
+
+        # Add cursor if provided
+        if after is not None:
+            request_params["after"] = after
+
+        # Remove None values
+        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._get_logs_api_call(pipeline_name, **request_params)
+
+        # 3. Inject the logic needed for subsequent fetches into the response object
+        page._inject_paginator(
+            fetch_func=lambda **kwargs: self._get_logs_api_call(pipeline_name, **kwargs),
+            # Base args for the *next* fetch don't include initial cursors
+            base_args={"limit": limit, "filter": request_params["filter"]},
+            cursor_param="after",  # Logs use 'after' cursor, not 'before' like pipelines
+        )
+        return page
 
+    async def _get_logs_api_call(self, pipeline_name: str, **kwargs: Any) -> PaginatedResponse[PipelineLog]:
+        """A private, stateless method that performs the raw API call for logs."""
         resp = await self._client.request(
-            endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}/logs",
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/{quote(pipeline_name, safe='')}/logs",
             method="GET",
-            params=params,
+            params=kwargs,
         )
 
         raise_for_status(resp)
 
         if resp.json is not None:
-            return PipelineLogList.model_validate(resp.json)
+            return PaginatedResponse[PipelineLog].create_with_cursor_field(resp.json, "logged_at")
         else:
-            # Return empty log list if no response
-            return PipelineLogList(data=[], has_more=False, total=0)
+            # Return empty paginated response if no JSON data
+            return PaginatedResponse[PipelineLog](data=[], has_more=False, total=0)
 
     async def deploy(self, pipeline_name: str) -> PipelineValidationResult:
         """Deploy a pipeline to production.
@@ -244,7 +280,9 @@ class PipelineResource(PipelineResourceProtocol):
         :raises UnexpectedAPIError: If the API returns an unexpected status code.
         """
         resp = await self._client.request(
-            endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}/deploy",
+            endpoint=(
+                f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/{quote(pipeline_name, safe='')}/deploy"
+            ),
             method="POST",
         )
 
@@ -274,7 +312,7 @@ class PipelineResource(PipelineResourceProtocol):
         :raises UnexpectedAPIError: If the API returns an unexpected status code.
         """
         resp = await self._client.request(
-            endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}",
+            endpoint=f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/{quote(pipeline_name, safe='')}",
             method="DELETE",
         )
 
@@ -315,7 +353,9 @@ class PipelineResource(PipelineResourceProtocol):
             data["filters"] = filters
 
         resp = await self._client.request(
-            endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}/search",
+            endpoint=(
+                f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/{quote(pipeline_name, safe='')}/search"
+            ),
             method="POST",
             data=data,
             response_type=dict[str, Any],
@@ -365,7 +405,10 @@ class PipelineResource(PipelineResourceProtocol):
             data["filters"] = filters
 
         async with self._client.stream_request(
-            endpoint=f"v1/workspaces/{self._workspace}/pipelines/{pipeline_name}/search-stream",
+            endpoint=(
+                f"v1/workspaces/{quote(self._workspace, safe='')}/pipelines/"
+                f"{quote(pipeline_name, safe='')}/search-stream"
+            ),
             method="POST",
             data=data,
         ) as resp:

deepset_mcp/api/pipeline_template/__init__.py

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

deepset_mcp/api/pipeline_template/models.py

@@ -20,22 +20,34 @@ class PipelineTemplateTag(BaseModel):
     """Model representing a tag on a pipeline template."""
 
     name: str
+    "Human-readable name of the tag"
     tag_id: UUID
+    "Unique identifier for the tag"
 
 
 class PipelineTemplate(BaseModel):
     """Model representing a pipeline template."""
 
     author: str
+    "Name of the template author or creator"
     best_for: list[str]
+    "List of use cases this template is best suited for"
     description: str
+    "Detailed description of the pipeline template"
     template_name: str = Field(alias="pipeline_name")
+    "Internal name identifier for the template"
     display_name: str = Field(alias="name")
+    "User-friendly display name for the template"
     pipeline_template_id: UUID = Field(alias="pipeline_template_id")
+    "Unique identifier for the pipeline template"
     potential_applications: list[str] = Field(alias="potential_applications")
+    "List of potential applications and scenarios for this template"
     yaml_config: str | None = None
+    "YAML configuration defining the pipeline structure"
     tags: list[PipelineTemplateTag]
+    "List of tags associated with the template for categorization"
     pipeline_type: PipelineType
+    "Type of pipeline (query or indexing)"
 
     @model_validator(mode="before")
     @classmethod
@@ -62,26 +74,3 @@ class PipelineTemplate(BaseModel):
             values["yaml_config"] = yaml_config
 
         return values
-
-
-class PipelineTemplateList(BaseModel):
-    """Response model for listing pipeline templates."""
-
-    data: list[PipelineTemplate]
-    has_more: bool
-    total: int
-
-
-class PipelineTemplateSearchResult(BaseModel):
-    """Model representing a search result for pipeline templates."""
-
-    template: PipelineTemplate
-    similarity_score: float
-
-
-class PipelineTemplateSearchResults(BaseModel):
-    """Response model for pipeline template search results."""
-
-    results: list[PipelineTemplateSearchResult]
-    query: str
-    total_found: int

deepset_mcp/api/pipeline_template/protocols.py

@@ -4,7 +4,8 @@
 
 from typing import Protocol
 
-from deepset_mcp.api.pipeline_template.models import PipelineTemplate, PipelineTemplateList
+from deepset_mcp.api.pipeline_template.models import PipelineTemplate
+from deepset_mcp.api.shared_models import PaginatedResponse
 
 
 class PipelineTemplateResourceProtocol(Protocol):
@@ -14,8 +15,13 @@ class PipelineTemplateResourceProtocol(Protocol):
         """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."""
+    async def list(
+        self,
+        limit: int = 10,
+        after: str | None = None,
+        field: str = "created_at",
+        order: str = "DESC",
+        filter: str | None = None,
+    ) -> PaginatedResponse[PipelineTemplate]:
+        """Lists pipeline templates and returns the first page of results with pagination support."""
         ...

deepset_mcp/api/pipeline_template/resource.py

@@ -5,9 +5,10 @@
 from typing import Any
 
 from deepset_mcp.api.exceptions import UnexpectedAPIError
-from deepset_mcp.api.pipeline_template.models import PipelineTemplate, PipelineTemplateList
+from deepset_mcp.api.pipeline_template.models import PipelineTemplate
 from deepset_mcp.api.pipeline_template.protocols import PipelineTemplateResourceProtocol
 from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.shared_models import PaginatedResponse
 from deepset_mcp.api.transport import raise_for_status
 
 
@@ -46,47 +47,58 @@ class PipelineTemplateResource(PipelineTemplateResourceProtocol):
 
         return PipelineTemplate.model_validate(data)
 
-    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.
-
-        Parameters
-        ----------
-        limit : int, optional (default=100)
-            Maximum number of templates to return
-        field : str, optional (default="created_at")
-            Field to sort by
-        order : str, optional (default="DESC")
-            Sort order (ASC or DESC)
-        filter : str | None, optional (default=None)
-            OData filter expression for filtering templates
-
-        Returns
-        -------
-        PipelineTemplateList
-            List of pipeline templates with metadata
+    async def list(
+        self,
+        limit: int = 10,
+        after: str | None = None,
+        field: str = "created_at",
+        order: str = "DESC",
+        filter: str | None = None,
+    ) -> PaginatedResponse[PipelineTemplate]:
+        """Lists pipeline templates and returns the first page of results.
+
+        The returned object can be iterated over to fetch subsequent pages.
+
+        :param limit: The maximum number of pipeline templates to return per page.
+        :param after: The cursor to fetch the next page of results.
+        :param field: Field to sort by (default: "created_at").
+        :param order: Sort order, either "ASC" or "DESC" (default: "DESC").
+        :param filter: OData filter expression for filtering templates.
+        :returns: A `PaginatedResponse` object containing the first page of pipeline templates.
         """
-        params = {"limit": limit, "page_number": 1, "field": field, "order": order}
-
+        # TODO: Remove when fixed
+        if after is not None:
+            raise ValueError("Pagination using 'after' parameter is currently not supported by the deepset platform.")
+
+        # 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 templates older than the current cursor
+        # TODO: while 'before' signals templates 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, "field": field, "order": order}
         if filter is not None:
-            params["filter"] = filter
+            request_params["filter"] = filter
+        request_params = {k: v for k, v in request_params.items() if v is not None}
 
-        response = await self._client.request(
-            f"/v1/workspaces/{self._workspace}/pipeline_templates",
-            method="GET",
-            params=params,
-        )
-
-        raise_for_status(response)
+        # 2. Make the first API call using a private, stateless method
+        page = await self._list_api_call(**request_params)
 
-        if response.json is None:
-            raise UnexpectedAPIError(message="Unexpected API response, no templates returned.")
-
-        response_data: dict[str, Any] = response.json
+        # 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, "filter": filter},
+        )
+        return page
 
-        return PipelineTemplateList(
-            data=[PipelineTemplate.model_validate(template) for template in response_data["data"]],
-            has_more=response_data.get("has_more", False),
-            total=response_data.get("total", len(response_data["data"])),
+    async def _list_api_call(self, **kwargs: Any) -> PaginatedResponse[PipelineTemplate]:
+        """A private, stateless method that performs the raw API call."""
+        resp = await self._client.request(
+            endpoint=f"v1/workspaces/{self._workspace}/pipeline_templates", 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 PaginatedResponse[PipelineTemplate].create_with_cursor_field(resp.json, "name")

deepset_mcp/api/protocols.py

@@ -4,18 +4,20 @@
 
 from contextlib import AbstractAsyncContextManager
 from types import TracebackType
-from typing import Any, Literal, Protocol, Self, TypeVar, overload
-
-from deepset_mcp.api.custom_components.protocols import CustomComponentsProtocol
-from deepset_mcp.api.haystack_service.protocols import HaystackServiceProtocol
-from deepset_mcp.api.indexes.protocols import IndexResourceProtocol
-from deepset_mcp.api.integrations.protocols import IntegrationResourceProtocol
-from deepset_mcp.api.pipeline.protocols import PipelineResourceProtocol
-from deepset_mcp.api.pipeline_template.protocols import PipelineTemplateResourceProtocol
-from deepset_mcp.api.secrets.protocols import SecretResourceProtocol
+from typing import TYPE_CHECKING, Any, Literal, Protocol, Self, TypeVar, overload
+
 from deepset_mcp.api.transport import StreamingResponse, TransportResponse
-from deepset_mcp.api.user.protocols import UserResourceProtocol
-from deepset_mcp.api.workspace.protocols import WorkspaceResourceProtocol
+
+if TYPE_CHECKING:
+    from deepset_mcp.api.custom_components.protocols import CustomComponentsProtocol
+    from deepset_mcp.api.haystack_service.protocols import HaystackServiceProtocol
+    from deepset_mcp.api.indexes.protocols import IndexResourceProtocol
+    from deepset_mcp.api.integrations.protocols import IntegrationResourceProtocol
+    from deepset_mcp.api.pipeline.protocols import PipelineResourceProtocol
+    from deepset_mcp.api.pipeline_template.protocols import PipelineTemplateResourceProtocol
+    from deepset_mcp.api.secrets.protocols import SecretResourceProtocol
+    from deepset_mcp.api.user.protocols import UserResourceProtocol
+    from deepset_mcp.api.workspace.protocols import WorkspaceResourceProtocol
 
 T = TypeVar("T")
 

deepset_mcp/api/secrets/__init__.py

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

deepset_mcp/api/secrets/models.py

@@ -9,12 +9,6 @@ class Secret(BaseModel):
     """Model representing a secret in deepset."""
 
     name: str
+    "Human-readable name of the secret"
     secret_id: str
-
-
-class SecretList(BaseModel):
-    """Model representing a list of secrets with pagination."""
-
-    data: list[Secret]
-    has_more: bool
-    total: int
+    "Unique identifier for the secret"

deepset_mcp/api/secrets/protocols.py

@@ -4,8 +4,8 @@
 
 from typing import Protocol
 
-from deepset_mcp.api.secrets.models import Secret, SecretList
-from deepset_mcp.api.shared_models import NoContentResponse
+from deepset_mcp.api.secrets.models import Secret
+from deepset_mcp.api.shared_models import NoContentResponse, PaginatedResponse
 
 
 class SecretResourceProtocol(Protocol):
@@ -16,7 +16,8 @@ class SecretResourceProtocol(Protocol):
         limit: int = 10,
         field: str = "created_at",
         order: str = "DESC",
-    ) -> SecretList:
+        after: str | None = None,
+    ) -> PaginatedResponse[Secret]:
         """List secrets with pagination."""
         ...
 

deepset_mcp/api/secrets/resource.py

@@ -6,9 +6,9 @@ from typing import Any
 
 from deepset_mcp.api.exceptions import ResourceNotFoundError
 from deepset_mcp.api.protocols import AsyncClientProtocol
-from deepset_mcp.api.secrets.models import Secret, SecretList
+from deepset_mcp.api.secrets.models import Secret
 from deepset_mcp.api.secrets.protocols import SecretResourceProtocol
-from deepset_mcp.api.shared_models import NoContentResponse
+from deepset_mcp.api.shared_models import NoContentResponse, PaginatedResponse
 from deepset_mcp.api.transport import raise_for_status
 
 
@@ -27,26 +27,51 @@ class SecretResource(SecretResourceProtocol):
         limit: int = 10,
         field: str = "created_at",
         order: str = "DESC",
-    ) -> SecretList:
+        after: str | None = None,
+    ) -> PaginatedResponse[Secret]:
         """List secrets with pagination.
 
+        The returned object can be iterated over to fetch subsequent pages.
+
         :param limit: Maximum number of secrets to return.
         :param field: Field to sort by.
         :param order: Sort order (ASC or DESC).
+        :param after: The cursor to fetch the next page of results.
 
-        :returns: List of secrets with pagination info.
+        :returns: A `PaginatedResponse` object containing the first page of secrets.
         """
-        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 secrets older than the current cursor
+        # TODO: while 'before' signals secrets 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": str(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": str(limit), "field": field, "order": order},
+        )
+        return page
 
+    async def _list_api_call(self, **kwargs: Any) -> PaginatedResponse[Secret]:
+        """A private, stateless method that performs the raw API call."""
         resp = await self._client.request(
             endpoint="v2/secrets",
             method="GET",
             response_type=dict[str, Any],
-            params=params,
+            params=kwargs,
         )
 
         raise_for_status(resp)
@@ -54,7 +79,7 @@ class SecretResource(SecretResourceProtocol):
         if resp.json is None:
             raise ResourceNotFoundError("Failed to retrieve secrets.")
 
-        return SecretList(**resp.json)
+        return PaginatedResponse[Secret].create_with_cursor_field(resp.json, "secret_id")
 
     async def create(self, name: str, secret: str) -> NoContentResponse:
         """Create a new secret.