Skip to content

feat: cursor-based pagination for messages #222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gabrycina wants to merge 1 commit into
base: main
Choose a base branch
from
+130 −8
Open

feat: cursor-based pagination for messages #222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 76 additions & 2 deletions src/agentex/resources/messages/messages.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,11 @@ def list(
*,
task_id: str,
limit: int | Omit = omit,
cursor: str | Omit = omit,
direction: str | Omit = omit,
page_number: int | Omit = omit,
order_by: str | Omit = omit,
order_direction: str | Omit = omit,
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
# The extra values given here take precedence over values defined on the client or passed to this method.
extra_headers: Headers | None = None,
Expand All @@ -190,18 +194,47 @@ def list(
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> MessageListResponse:
"""
List Messages
List Messages with cursor-based pagination.
Returns messages for a task with pagination metadata.
Use the `next_cursor` from the response to fetch the next page.
Args:
task_id: The task ID
limit: Maximum number of messages to return (default: 50)
cursor: Opaque cursor string for pagination. Pass the `next_cursor` from
a previous response to get the next page.
direction: Pagination direction - "older" to get older messages (default),
"newer" to get newer messages.
page_number: [DEPRECATED] Use cursor instead. Page number for offset pagination.
order_by: Field to order by (default: created_at)
order_direction: Order direction - "asc" or "desc" (default: desc)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
Example:
# First request
response = client.messages.list(task_id="xxx", limit=50)
# Next page
if response.has_more:
next_page = client.messages.list(
task_id="xxx",
limit=50,
cursor=response.next_cursor
)
"""
return self._get(
"/messages",
Expand All @@ -214,7 +247,11 @@ def list(
{
"task_id": task_id,
"limit": limit,
"cursor": cursor,
"direction": direction,
"page_number": page_number,
"order_by": order_by,
"order_direction": order_direction,
},
message_list_params.MessageListParams,
),
Expand Down Expand Up @@ -370,7 +407,11 @@ async def list(
*,
task_id: str,
limit: int | Omit = omit,
cursor: str | Omit = omit,
direction: str | Omit = omit,
page_number: int | Omit = omit,
order_by: str | Omit = omit,
order_direction: str | Omit = omit,
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
# The extra values given here take precedence over values defined on the client or passed to this method.
extra_headers: Headers | None = None,
Expand All @@ -379,18 +420,47 @@ async def list(
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> MessageListResponse:
"""
List Messages
List Messages with cursor-based pagination.
Returns messages for a task with pagination metadata.
Use the `next_cursor` from the response to fetch the next page.
Args:
task_id: The task ID
limit: Maximum number of messages to return (default: 50)
cursor: Opaque cursor string for pagination. Pass the `next_cursor` from
a previous response to get the next page.
direction: Pagination direction - "older" to get older messages (default),
"newer" to get newer messages.
page_number: [DEPRECATED] Use cursor instead. Page number for offset pagination.
order_by: Field to order by (default: created_at)
order_direction: Order direction - "asc" or "desc" (default: desc)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
Example:
# First request
response = await client.messages.list(task_id="xxx", limit=50)
# Next page
if response.has_more:
next_page = await client.messages.list(
task_id="xxx",
limit=50,
cursor=response.next_cursor
)
"""
return await self._get(
"/messages",
Expand All @@ -403,7 +473,11 @@ async def list(
{
"task_id": task_id,
"limit": limit,
"cursor": cursor,
"direction": direction,
"page_number": page_number,
"order_by": order_by,
"order_direction": order_direction,
},
message_list_params.MessageListParams,
),
Expand Down
1 change: 1 addition & 0 deletions src/agentex/types/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@
from .tool_request_content import ToolRequestContent as ToolRequestContent
from .message_create_params import MessageCreateParams as MessageCreateParams
from .message_list_response import MessageListResponse as MessageListResponse
from .message_list_response import PaginatedMessagesResponse as PaginatedMessagesResponse
from .message_update_params import MessageUpdateParams as MessageUpdateParams
from .tool_response_content import ToolResponseContent as ToolResponseContent
from .tracker_list_response import TrackerListResponse as TrackerListResponse
Expand Down
16 changes: 16 additions & 0 deletions src/agentex/types/message_list_params.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,21 @@ class MessageListParams(TypedDict, total=False):
"""The task ID"""

limit: int
"""Maximum number of messages to return (default: 50)"""

cursor: str
"""Opaque cursor string for pagination. Pass the `next_cursor` from
a previous response to get the next page."""

direction: str
"""Pagination direction - "older" to get older messages (default),
"newer" to get newer messages."""

page_number: int
"""[DEPRECATED] Use cursor instead. Page number for offset-based pagination (default: 1)"""

order_by: str
"""Field to order by (default: created_at)"""

order_direction: str
"""Order direction - "asc" or "desc" (default: desc)"""
25 changes: 21 additions & 4 deletions src/agentex/types/message_list_response.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,27 @@
# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from typing import List
from typing_extensions import TypeAlias
from typing import List, Optional

from .._models import BaseModel
from .task_message import TaskMessage

__all__ = ["MessageListResponse"]
__all__ = ["MessageListResponse", "PaginatedMessagesResponse"]

MessageListResponse: TypeAlias = List[TaskMessage]

class PaginatedMessagesResponse(BaseModel):
"""Response with cursor pagination metadata."""

data: List[TaskMessage]
"""List of messages"""

next_cursor: Optional[str] = None
"""Cursor for fetching the next page of older messages.
Pass this as the `cursor` parameter in the next request.
None if there are no more messages."""

has_more: bool = False
"""Whether there are more messages to fetch"""


# Alias for backwards compatibility
MessageListResponse = PaginatedMessagesResponse
18 changes: 16 additions & 2 deletions tests/api_resources/test_messages.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,10 +240,17 @@ def test_method_list(self, client: Agentex) -> None:
def test_method_list_with_all_params(self, client: Agentex) -> None:
message = client.messages.list(
task_id="task_id",
limit=0,
limit=50,
cursor="eyJ2IjoxLCJpZCI6Im1zZ18xMjMiLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMCJ9",
direction="older",
page_number=0,
order_by="created_at",
order_direction="desc",
)
assert_matches_type(MessageListResponse, message, path=["response"])
# Response should have data, next_cursor, and has_more
assert hasattr(message, "data")
assert hasattr(message, "has_more")

@pytest.mark.skip(reason="Prism tests are disabled")
@parametrize
Expand Down Expand Up @@ -496,10 +503,17 @@ async def test_method_list(self, async_client: AsyncAgentex) -> None:
async def test_method_list_with_all_params(self, async_client: AsyncAgentex) -> None:
message = await async_client.messages.list(
task_id="task_id",
limit=0,
limit=50,
cursor="eyJ2IjoxLCJpZCI6Im1zZ18xMjMiLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMCJ9",
direction="older",
page_number=0,
order_by="created_at",
order_direction="desc",
)
assert_matches_type(MessageListResponse, message, path=["response"])
# Response should have data, next_cursor, and has_more
assert hasattr(message, "data")
assert hasattr(message, "has_more")

@pytest.mark.skip(reason="Prism tests are disabled")
@parametrize
Expand Down
Loading