feat(api): more pagination schemes

Author: stainless-app[bot]

.stats.yml

@@ -1,3 +1,3 @@
 configured_endpoints: 55
 openapi_spec_hash: f17890d85522687a4c68702da9ad2efb
-config_hash: 86582a50eb22b2866777cbd4d94f4e8d
+config_hash: 8f6e5c3b064cbb77569a6bf654954a56

api.md

@@ -214,7 +214,7 @@ Methods:
 - <code title="get /api/projects/{project_id}/query_logs/{query_log_id}">client.projects.query_logs.<a href="./src/codex/resources/projects/query_logs.py">retrieve</a>(query_log_id, \*, project_id) -> <a href="./src/codex/types/projects/query_log_retrieve_response.py">QueryLogRetrieveResponse</a></code>
 - <code title="get /api/projects/{project_id}/query_logs/">client.projects.query_logs.<a href="./src/codex/resources/projects/query_logs.py">list</a>(project_id, \*\*<a href="src/codex/types/projects/query_log_list_params.py">params</a>) -> <a href="./src/codex/types/projects/query_log_list_response.py">SyncOffsetPageQueryLogs[QueryLogListResponse]</a></code>
 - <code title="get /api/projects/{project_id}/query_logs/logs_by_group">client.projects.query_logs.<a href="./src/codex/resources/projects/query_logs.py">list_by_group</a>(project_id, \*\*<a href="src/codex/types/projects/query_log_list_by_group_params.py">params</a>) -> <a href="./src/codex/types/projects/query_log_list_by_group_response.py">QueryLogListByGroupResponse</a></code>
-- <code title="get /api/projects/{project_id}/query_logs/groups">client.projects.query_logs.<a href="./src/codex/resources/projects/query_logs.py">list_groups</a>(project_id, \*\*<a href="src/codex/types/projects/query_log_list_groups_params.py">params</a>) -> <a href="./src/codex/types/projects/query_log_list_groups_response.py">QueryLogListGroupsResponse</a></code>
+- <code title="get /api/projects/{project_id}/query_logs/groups">client.projects.query_logs.<a href="./src/codex/resources/projects/query_logs.py">list_groups</a>(project_id, \*\*<a href="src/codex/types/projects/query_log_list_groups_params.py">params</a>) -> <a href="./src/codex/types/projects/query_log_list_groups_response.py">SyncOffsetPageQueryLogGroups[QueryLogListGroupsResponse]</a></code>
 - <code title="post /api/projects/{project_id}/query_logs/{query_log_id}/start_remediation">client.projects.query_logs.<a href="./src/codex/resources/projects/query_logs.py">start_remediation</a>(query_log_id, \*, project_id) -> <a href="./src/codex/types/projects/query_log_start_remediation_response.py">QueryLogStartRemediationResponse</a></code>
 
 ## Remediations

src/codex/pagination.py

@@ -18,6 +18,10 @@
     "AsyncOffsetPageQueryLogs",
     "SyncOffsetPageRemediations",
     "AsyncOffsetPageRemediations",
+    "SyncOffsetPageQueryLogGroups",
+    "AsyncOffsetPageQueryLogGroups",
+    "SyncOffsetPageQueryLogsByGroup",
+    "AsyncOffsetPageQueryLogsByGroup",
 ]
 
 _BaseModelT = TypeVar("_BaseModelT", bound=BaseModel)
@@ -265,3 +269,123 @@ def next_page_info(self) -> Optional[PageInfo]:
             return PageInfo(params={"offset": current_count})
 
         return None
+
+
+class SyncOffsetPageQueryLogGroups(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    query_log_groups: List[_T]
+    total_count: Optional[int] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        query_log_groups = self.query_log_groups
+        if not query_log_groups:
+            return []
+        return query_log_groups
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        offset = self._options.params.get("offset") or 0
+        if not isinstance(offset, int):
+            raise ValueError(f'Expected "offset" param to be an integer but got {offset}')
+
+        length = len(self._get_page_items())
+        current_count = offset + length
+
+        total_count = self.total_count
+        if total_count is None:
+            return None
+
+        if current_count < total_count:
+            return PageInfo(params={"offset": current_count})
+
+        return None
+
+
+class AsyncOffsetPageQueryLogGroups(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
+    query_log_groups: List[_T]
+    total_count: Optional[int] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        query_log_groups = self.query_log_groups
+        if not query_log_groups:
+            return []
+        return query_log_groups
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        offset = self._options.params.get("offset") or 0
+        if not isinstance(offset, int):
+            raise ValueError(f'Expected "offset" param to be an integer but got {offset}')
+
+        length = len(self._get_page_items())
+        current_count = offset + length
+
+        total_count = self.total_count
+        if total_count is None:
+            return None
+
+        if current_count < total_count:
+            return PageInfo(params={"offset": current_count})
+
+        return None
+
+
+class SyncOffsetPageQueryLogsByGroup(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    query_logs_by_group: List[_T]
+    total_count: Optional[int] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        query_logs_by_group = self.query_logs_by_group
+        if not query_logs_by_group:
+            return []
+        return query_logs_by_group
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        offset = self._options.params.get("offset") or 0
+        if not isinstance(offset, int):
+            raise ValueError(f'Expected "offset" param to be an integer but got {offset}')
+
+        length = len(self._get_page_items())
+        current_count = offset + length
+
+        total_count = self.total_count
+        if total_count is None:
+            return None
+
+        if current_count < total_count:
+            return PageInfo(params={"offset": current_count})
+
+        return None
+
+
+class AsyncOffsetPageQueryLogsByGroup(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
+    query_logs_by_group: List[_T]
+    total_count: Optional[int] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        query_logs_by_group = self.query_logs_by_group
+        if not query_logs_by_group:
+            return []
+        return query_logs_by_group
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        offset = self._options.params.get("offset") or 0
+        if not isinstance(offset, int):
+            raise ValueError(f'Expected "offset" param to be an integer but got {offset}')
+
+        length = len(self._get_page_items())
+        current_count = offset + length
+
+        total_count = self.total_count
+        if total_count is None:
+            return None
+
+        if current_count < total_count:
+            return PageInfo(params={"offset": current_count})
+
+        return None

src/codex/resources/projects/query_logs.py

@@ -18,7 +18,12 @@
     async_to_raw_response_wrapper,
     async_to_streamed_response_wrapper,
 )
-from ...pagination import SyncOffsetPageQueryLogs, AsyncOffsetPageQueryLogs
+from ...pagination import (
+    SyncOffsetPageQueryLogs,
+    AsyncOffsetPageQueryLogs,
+    SyncOffsetPageQueryLogGroups,
+    AsyncOffsetPageQueryLogGroups,
+)
 from ..._base_client import AsyncPaginator, make_request_options
 from ...types.projects import query_log_list_params, query_log_list_groups_params, query_log_list_by_group_params
 from ...types.projects.query_log_list_response import QueryLogListResponse
@@ -290,7 +295,7 @@ def list_groups(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    ) -> QueryLogListGroupsResponse:
+    ) -> SyncOffsetPageQueryLogGroups[QueryLogListGroupsResponse]:
         """
         List query log groups by project ID.
 
@@ -323,8 +328,9 @@ def list_groups(
         """
         if not project_id:
             raise ValueError(f"Expected a non-empty value for `project_id` but received {project_id!r}")
-        return self._get(
+        return self._get_api_list(
             f"/api/projects/{project_id}/query_logs/groups",
+            page=SyncOffsetPageQueryLogGroups[QueryLogListGroupsResponse],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -349,7 +355,7 @@ def list_groups(
                     query_log_list_groups_params.QueryLogListGroupsParams,
                 ),
             ),
-            cast_to=QueryLogListGroupsResponse,
+            model=QueryLogListGroupsResponse,
         )
 
     def start_remediation(
@@ -622,7 +628,7 @@ async def list_by_group(
             cast_to=QueryLogListByGroupResponse,
         )
 
-    async def list_groups(
+    def list_groups(
         self,
         project_id: str,
         *,
@@ -649,7 +655,7 @@ async def list_groups(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    ) -> QueryLogListGroupsResponse:
+    ) -> AsyncPaginator[QueryLogListGroupsResponse, AsyncOffsetPageQueryLogGroups[QueryLogListGroupsResponse]]:
         """
         List query log groups by project ID.
 
@@ -682,14 +688,15 @@ async def list_groups(
         """
         if not project_id:
             raise ValueError(f"Expected a non-empty value for `project_id` but received {project_id!r}")
-        return await self._get(
+        return self._get_api_list(
             f"/api/projects/{project_id}/query_logs/groups",
+            page=AsyncOffsetPageQueryLogGroups[QueryLogListGroupsResponse],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
                 extra_body=extra_body,
                 timeout=timeout,
-                query=await async_maybe_transform(
+                query=maybe_transform(
                     {
                         "created_at_end": created_at_end,
                         "created_at_start": created_at_start,
@@ -708,7 +715,7 @@ async def list_groups(
                     query_log_list_groups_params.QueryLogListGroupsParams,
                 ),
             ),
-            cast_to=QueryLogListGroupsResponse,
+            model=QueryLogListGroupsResponse,
         )
 
     async def start_remediation(

src/codex/types/projects/query_log_list_groups_response.py

@@ -8,41 +8,40 @@
 
 __all__ = [
     "QueryLogListGroupsResponse",
-    "QueryLogGroup",
-    "QueryLogGroupFormattedEscalationEvalScores",
-    "QueryLogGroupFormattedEvalScores",
-    "QueryLogGroupFormattedGuardrailEvalScores",
-    "QueryLogGroupFormattedNonGuardrailEvalScores",
-    "QueryLogGroupContext",
-    "QueryLogGroupDeterministicGuardrailsResults",
+    "FormattedEscalationEvalScores",
+    "FormattedEvalScores",
+    "FormattedGuardrailEvalScores",
+    "FormattedNonGuardrailEvalScores",
+    "Context",
+    "DeterministicGuardrailsResults",
 ]
 
 
-class QueryLogGroupFormattedEscalationEvalScores(BaseModel):
+class FormattedEscalationEvalScores(BaseModel):
     score: float
 
     status: Literal["pass", "fail"]
 
 
-class QueryLogGroupFormattedEvalScores(BaseModel):
+class FormattedEvalScores(BaseModel):
     score: float
 
     status: Literal["pass", "fail"]
 
 
-class QueryLogGroupFormattedGuardrailEvalScores(BaseModel):
+class FormattedGuardrailEvalScores(BaseModel):
     score: float
 
     status: Literal["pass", "fail"]
 
 
-class QueryLogGroupFormattedNonGuardrailEvalScores(BaseModel):
+class FormattedNonGuardrailEvalScores(BaseModel):
     score: float
 
     status: Literal["pass", "fail"]
 
 
-class QueryLogGroupContext(BaseModel):
+class Context(BaseModel):
     content: str
     """The actual content/text of the document."""
 
@@ -59,32 +58,32 @@ class QueryLogGroupContext(BaseModel):
     """Title or heading of the document. Useful for display and context."""
 
 
-class QueryLogGroupDeterministicGuardrailsResults(BaseModel):
+class DeterministicGuardrailsResults(BaseModel):
     guardrail_name: str
 
     should_guardrail: bool
 
     matches: Optional[List[str]] = None
 
 
-class QueryLogGroup(BaseModel):
+class QueryLogListGroupsResponse(BaseModel):
     id: str
 
     created_at: datetime
 
-    formatted_escalation_eval_scores: Optional[Dict[str, QueryLogGroupFormattedEscalationEvalScores]] = None
+    formatted_escalation_eval_scores: Optional[Dict[str, FormattedEscalationEvalScores]] = None
 
-    formatted_eval_scores: Optional[Dict[str, QueryLogGroupFormattedEvalScores]] = None
+    formatted_eval_scores: Optional[Dict[str, FormattedEvalScores]] = None
     """Format evaluation scores for frontend display with pass/fail status.
 
     Returns: Dictionary mapping eval keys to their formatted representation: {
     "eval_key": { "score": float, "status": "pass" | "fail" } } Returns None if
     eval_scores is None.
     """
 
-    formatted_guardrail_eval_scores: Optional[Dict[str, QueryLogGroupFormattedGuardrailEvalScores]] = None
+    formatted_guardrail_eval_scores: Optional[Dict[str, FormattedGuardrailEvalScores]] = None
 
-    formatted_non_guardrail_eval_scores: Optional[Dict[str, QueryLogGroupFormattedNonGuardrailEvalScores]] = None
+    formatted_non_guardrail_eval_scores: Optional[Dict[str, FormattedNonGuardrailEvalScores]] = None
 
     is_bad_response: bool
 
@@ -103,7 +102,7 @@ class QueryLogGroup(BaseModel):
     was_cache_hit: Optional[bool] = None
     """If similar query already answered, or None if cache was not checked"""
 
-    context: Optional[List[QueryLogGroupContext]] = None
+    context: Optional[List[Context]] = None
     """RAG context used for the query"""
 
     custom_metadata: Optional[object] = None
@@ -112,7 +111,7 @@ class QueryLogGroup(BaseModel):
     custom_metadata_keys: Optional[List[str]] = None
     """Keys of the custom metadata"""
 
-    deterministic_guardrails_results: Optional[Dict[str, QueryLogGroupDeterministicGuardrailsResults]] = None
+    deterministic_guardrails_results: Optional[Dict[str, DeterministicGuardrailsResults]] = None
     """Results of deterministic guardrails applied to the query"""
 
     escalated: Optional[bool] = None
@@ -144,11 +143,3 @@ class QueryLogGroup(BaseModel):
 
     primary_eval_issue_score: Optional[float] = None
     """Score of the primary eval issue"""
-
-
-class QueryLogListGroupsResponse(BaseModel):
-    custom_metadata_columns: List[str]
-
-    query_log_groups: List[QueryLogGroup]
-
-    total_count: int