[feat] Group revision queries by parent

.all-contributorsrc

@@ -807,6 +807,15 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "Christian-Sidak",
+      "name": "Christian Sidak",
+      "avatar_url": "https://avatars.githubusercontent.com/u/61099993?v=4",
+      "profile": "https://christiansidak.com",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,

README.md

@@ -256,7 +256,7 @@ If Agenta is useful to you, star the repository and tell us what you build.
 ## Contributors ✨
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-86-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-87-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -377,6 +377,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://www.heysuraj.dev/"><img src="https://avatars.githubusercontent.com/u/46050946?v=4?s=100" width="100px;" alt="suraj ✨ "/><br /><sub><b>suraj ✨ </b></sub></a><br /><a href="https://github.com/Agenta-AI/agenta/commits?author=uchiha-suraj" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://oforiwaasam.github.io/portfolio/"><img src="https://avatars.githubusercontent.com/u/41793292?v=4?s=100" width="100px;" alt="Lily Sam"/><br /><sub><b>Lily Sam</b></sub></a><br /><a href="https://github.com/Agenta-AI/agenta/commits?author=oforiwaasam" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://christiansidak.com"><img src="https://avatars.githubusercontent.com/u/61099993?v=4?s=100" width="100px;" alt="Christian Sidak"/><br /><sub><b>Christian Sidak</b></sub></a><br /><a href="https://github.com/Agenta-AI/agenta/commits?author=Christian-Sidak" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

api/oss/src/apis/fastapi/applications/models.py

@@ -1,6 +1,8 @@
 from typing import Any, Dict, Optional, List
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
+
+from oss.src.core.git.dtos import RevisionGrouping, validate_revision_grouping
 
 from oss.src.core.shared.dtos import (
     Reference,
@@ -342,11 +344,38 @@ class ApplicationRevisionQueryRequest(BaseModel):
         description="When `true`, include archived revisions. Defaults to `false`.",
     )
     #
+    grouping: Optional[RevisionGrouping] = Field(
+        default=None,
+        description=(
+            "Divide matching revisions by artifact or variant and select one "
+            "revision from each group."
+        ),
+    )
+    #
     windowing: Optional[Windowing] = Field(
         default=None,
         description="Cursor pagination and time-range controls.",
     )
 
+    @model_validator(mode="after")
+    def _validate_grouping(self):
+        validate_revision_grouping(
+            grouping=self.grouping,
+            artifact_refs=self.application_refs,
+            variant_refs=self.application_variant_refs,
+            revision_refs=self.application_revision_refs,
+            windowing=self.windowing,
+        )
+        if (
+            self.grouping
+            and self.application_revision
+            and self.application_revision.flags
+        ):
+            raise ValueError(
+                "grouping cannot be combined with application revision flags"
+            )
+        return self
+
 
 class ApplicationRevisionCommitRequest(BaseModel):
     """Request body for committing a new revision on a variant.

api/oss/src/apis/fastapi/applications/router.py

@@ -1605,6 +1605,8 @@ async def query_application_revisions(
             #
             include_archived=application_revision_query_request.include_archived,
             #
+            grouping=application_revision_query_request.grouping,
+            #
             windowing=application_revision_query_request.windowing,
         )
 

api/oss/src/apis/fastapi/environments/models.py

@@ -1,6 +1,8 @@
 from typing import Optional, List
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
+
+from oss.src.core.git.dtos import RevisionGrouping, validate_revision_grouping
 
 from oss.src.core.shared.dtos import (
     Windowing,
@@ -141,8 +143,29 @@ class EnvironmentRevisionQueryRequest(BaseModel):
     #
     include_archived: Optional[bool] = None
     #
+    grouping: Optional[RevisionGrouping] = Field(
+        default=None,
+        description=(
+            "Divide matching revisions by artifact or variant and select one "
+            "revision from each group."
+        ),
+    )
+    #
     windowing: Optional[Windowing] = None
 
+    @model_validator(mode="after")
+    def _validate_grouping(self):
+        validate_revision_grouping(
+            grouping=self.grouping,
+            artifact_refs=self.environment_refs,
+            variant_refs=self.environment_variant_refs,
+            revision_refs=self.environment_revision_refs,
+            windowing=self.windowing,
+        )
+        if self.grouping and self.references:
+            raise ValueError("grouping cannot be combined with environment references")
+        return self
+
 
 class EnvironmentRevisionCommitRequest(BaseModel):
     environment_revision: EnvironmentRevisionCommit

api/oss/src/apis/fastapi/environments/router.py

@@ -1,7 +1,7 @@
 from typing import Optional
 from uuid import UUID
 
-from fastapi import APIRouter, Request, status, Depends, HTTPException
+from fastapi import APIRouter, Body, Request, status, Depends, HTTPException
 
 from oss.src.utils.common import is_ee
 from oss.src.utils.logging import get_module_logger
@@ -67,7 +67,6 @@
     parse_environment_variant_query_request_from_body,
     merge_environment_variant_query_requests,
     parse_environment_revision_query_request_from_params,
-    parse_environment_revision_query_request_from_body,
     merge_environment_revision_query_requests,
     ensure_environment_deploy_allowed,
 )
@@ -1062,6 +1061,7 @@ async def query_environment_revisions(
         query_request_params: Optional[EnvironmentRevisionQueryRequest] = Depends(
             parse_environment_revision_query_request_from_params
         ),
+        query_request_body: Optional[EnvironmentRevisionQueryRequest] = Body(None),
     ) -> EnvironmentRevisionsResponse:
         if not await check_action_access(  # type: ignore
             user_uid=request.state.user_id,
@@ -1070,24 +1070,6 @@ async def query_environment_revisions(
         ):
             raise FORBIDDEN_EXCEPTION  # type: ignore
 
-        body_json = None
-        query_request_body = None
-
-        try:
-            body_json = await request.json()
-
-            if body_json:
-                query_request_body = parse_environment_revision_query_request_from_body(
-                    **body_json
-                )
-
-        except Exception as exc:
-            # Ignore JSON parsing issues and proceed without a body filter.
-            log.debug(
-                "Failed to parse environment revision query request body as JSON: %s",
-                exc,
-            )
-
         environment_revision_query_request = merge_environment_revision_query_requests(
             query_request_params,
             query_request_body,
@@ -1106,6 +1088,8 @@ async def query_environment_revisions(
             #
             include_archived=environment_revision_query_request.include_archived,
             #
+            grouping=environment_revision_query_request.grouping,
+            #
             windowing=environment_revision_query_request.windowing,
         )
 

api/oss/src/apis/fastapi/environments/utils.py

@@ -1,4 +1,5 @@
 from typing import Optional, Literal, List
+from oss.src.core.git.dtos import RevisionGrouping
 from uuid import UUID
 from datetime import datetime
 
@@ -552,31 +553,20 @@ def parse_environment_revision_query_request_from_body(
     #
     include_archived: Optional[bool] = None,
     #
+    grouping: Optional[RevisionGrouping] = None,
+    #
     windowing: Optional[Windowing] = None,
 ) -> EnvironmentRevisionQueryRequest:
-    environment_revision_query_request = None
-
-    try:
-        environment_revision_query_request = EnvironmentRevisionQueryRequest(
-            environment_revision=environment_revision,
-            #
-            environment_refs=environment_refs,
-            environment_variant_refs=environment_variant_refs,
-            environment_revision_refs=environment_revision_refs,
-            #
-            references=references,
-            #
-            include_archived=include_archived,
-            #
-            windowing=windowing,
-        )
-
-    except Exception as e:  # pylint: disable=broad-except
-        log.warn(e)
-
-        environment_revision_query_request = EnvironmentRevisionQueryRequest()
-
-    return environment_revision_query_request
+    return EnvironmentRevisionQueryRequest(
+        environment_revision=environment_revision,
+        environment_refs=environment_refs,
+        environment_variant_refs=environment_variant_refs,
+        environment_revision_refs=environment_revision_refs,
+        references=references,
+        include_archived=include_archived,
+        grouping=grouping,
+        windowing=windowing,
+    )
 
 
 def merge_environment_revision_query_requests(
@@ -609,6 +599,8 @@ def merge_environment_revision_query_requests(
                 else query_request_params.include_archived
             ),
             #
+            grouping=query_request_body.grouping or query_request_params.grouping,
+            #
             windowing=query_request_body.windowing or query_request_params.windowing,
         )
 

api/oss/src/apis/fastapi/evaluators/models.py

@@ -1,6 +1,8 @@
 from typing import Optional, List, Dict, Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
+
+from oss.src.core.git.dtos import RevisionGrouping, validate_revision_grouping
 
 from oss.src.core.shared.dtos import (
     Windowing,
@@ -261,11 +263,34 @@ class EvaluatorRevisionQueryRequest(BaseModel):
         description="When true, include soft-deleted revisions.",
     )
     #
+    grouping: Optional[RevisionGrouping] = Field(
+        default=None,
+        description=(
+            "Divide matching revisions by artifact or variant and select one "
+            "revision from each group."
+        ),
+    )
+    #
     windowing: Optional[Windowing] = Field(
         default=None,
         description="Cursor-based pagination controls.",
     )
 
+    @model_validator(mode="after")
+    def _validate_grouping(self):
+        validate_revision_grouping(
+            grouping=self.grouping,
+            artifact_refs=self.evaluator_refs,
+            variant_refs=self.evaluator_variant_refs,
+            revision_refs=self.evaluator_revision_refs,
+            windowing=self.windowing,
+        )
+        if self.grouping and self.evaluator_revision and self.evaluator_revision.flags:
+            raise ValueError(
+                "grouping cannot be combined with evaluator revision flags"
+            )
+        return self
+
 
 class EvaluatorRevisionCommitRequest(BaseModel):
     """Body for committing a new revision on a variant."""

api/oss/src/apis/fastapi/evaluators/router.py

@@ -1608,6 +1608,8 @@ async def query_evaluator_revisions(
             #
             include_archived=evaluator_revision_query_request.include_archived,
             #
+            grouping=evaluator_revision_query_request.grouping,
+            #
             windowing=evaluator_revision_query_request.windowing,
         )
 

api/oss/src/apis/fastapi/queries/models.py

@@ -1,6 +1,8 @@
 from typing import Optional, List
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
+
+from oss.src.core.git.dtos import RevisionGrouping, validate_revision_grouping
 
 from oss.src.core.shared.dtos import (
     Reference,
@@ -135,8 +137,27 @@ class QueryRevisionQueryRequest(BaseModel):
     #
     include_archived: Optional[bool] = None
     #
+    grouping: Optional[RevisionGrouping] = Field(
+        default=None,
+        description=(
+            "Divide matching revisions by artifact or variant and select one "
+            "revision from each group."
+        ),
+    )
+    #
     windowing: Optional[Windowing] = None
 
+    @model_validator(mode="after")
+    def _validate_grouping(self):
+        validate_revision_grouping(
+            grouping=self.grouping,
+            artifact_refs=self.query_refs,
+            variant_refs=self.query_variant_refs,
+            revision_refs=self.query_revision_refs,
+            windowing=self.windowing,
+        )
+        return self
+
 
 class QueryRevisionCommitRequest(BaseModel):
     query_revision: QueryRevisionCommit

api/oss/src/apis/fastapi/queries/router.py

@@ -912,6 +912,8 @@ async def query_query_revisions(
             #
             include_archived=query_revision_query_request.include_archived,
             #
+            grouping=query_revision_query_request.grouping,
+            #
             windowing=query_revision_query_request.windowing,
         )
 

api/oss/src/apis/fastapi/testsets/models.py

@@ -1,6 +1,8 @@
 from typing import Optional, List
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
+
+from oss.src.core.git.dtos import RevisionGrouping, validate_revision_grouping
 
 from oss.src.core.shared.dtos import (
     Windowing,
@@ -229,11 +231,30 @@ class TestsetRevisionQueryRequest(BaseModel):
         description="Include full testcase objects for each returned revision. Defaults to true.",
     )
     #
+    grouping: Optional[RevisionGrouping] = Field(
+        default=None,
+        description=(
+            "Divide matching revisions by artifact or variant and select one "
+            "revision from each group."
+        ),
+    )
+    #
     windowing: Optional[Windowing] = Field(
         default=None,
         description="Cursor-based pagination. See the Query Pattern guide.",
     )
 
+    @model_validator(mode="after")
+    def _validate_grouping(self):
+        validate_revision_grouping(
+            grouping=self.grouping,
+            artifact_refs=self.testset_refs,
+            variant_refs=self.testset_variant_refs,
+            revision_refs=self.testset_revision_refs,
+            windowing=self.windowing,
+        )
+        return self
+
 
 class TestsetRevisionCommitRequest(BaseModel):
     testset_revision: TestsetRevisionCommit = Field(

api/oss/src/apis/fastapi/testsets/router.py

@@ -1420,6 +1420,8 @@ async def query_testset_revisions(
             include_archived=testset_revision_query_request.include_archived,
             include_testcases=testset_revision_query_request.include_testcases,
             #
+            grouping=testset_revision_query_request.grouping,
+            #
             windowing=testset_revision_query_request.windowing,
         )