Add orderby field to postgres endpoints (#84)

MichaelSun48 · web-flow · commit 35707928c2b2 · 2025-11-26T12:04:27.000-08:00
Adds an order_by field to the following model's get endpoints: 
1. Tasks 
2. Agents
3. Spans 
4. Agent Task Tracker 
5. Deployment History

I've only made this change to the postgres models since it was easy to
just expose the order_by field in the ORM up to the API layer. Doing it
for the mongoDB objects might be _slightly_ more complex and should
probably come in a separate PR.
diff --git a/agentex/src/api/routes/agent_task_tracker.py b/agentex/src/api/routes/agent_task_tracker.py
@@ -52,12 +52,19 @@ async def filter_agent_task_tracker(
     task_id: str | None = Query(None, description="Task ID"),
     limit: int = Query(50, description="Limit", ge=1),
     page_number: int = Query(1, description="Page number", ge=1),
+    order_by: str | None = Query(None, description="Field to order by"),
+    order_direction: str = Query("desc", description="Order direction (asc or desc)"),
 ) -> list[AgentTaskTracker]:
     """
     Filter agent task tracker by query parameters.
     """
     agent_task_tracker_entities = await agent_task_tracker_use_case.list(
-        agent_id=agent_id, task_id=task_id, limit=limit, page_number=page_number
+        agent_id=agent_id,
+        task_id=task_id,
+        limit=limit,
+        page_number=page_number,
+        order_by=order_by,
+        order_direction=order_direction,
     )
     return [
         AgentTaskTracker.model_validate(entity)
diff --git a/agentex/src/api/routes/agents.py b/agentex/src/api/routes/agents.py
@@ -95,12 +95,16 @@ async def list_agents(
     task_id: str | None = Query(None, description="Task ID"),
     limit: int = Query(50, description="Limit", ge=1),
     page_number: int = Query(1, description="Page number", ge=1),
+    order_by: str | None = Query(None, description="Field to order by"),
+    order_direction: str = Query("desc", description="Order direction (asc or desc)"),
 ):
     """List all registered agents."""
     agent_entities = await agents_use_case.list(
         task_id=task_id,
         limit=limit,
         page_number=page_number,
+        order_by=order_by,
+        order_direction=order_direction,
         **{"id": _authorized_ids} if _authorized_ids is not None else {},
     )
     return [Agent.model_validate(agent_entity) for agent_entity in agent_entities]
diff --git a/agentex/src/api/routes/deployment_history.py b/agentex/src/api/routes/deployment_history.py
@@ -49,6 +49,8 @@ async def list_deployments(
     agent_name: str | None = None,
     limit: int = 50,
     page_number: int = 1,
+    order_by: str | None = None,
+    order_direction: str = "desc",
 ) -> list[DeploymentHistory]:
     """List deployment history"""
     if not agent_id and not agent_name:
@@ -63,7 +65,11 @@ async def list_deployments(
         )
     agent = await agent_use_case.get(id=agent_id, name=agent_name)
     deployments = await deployment_history_use_case.list_deployments(
-        agent_id=agent.id, limit=limit, page_number=page_number
+        agent_id=agent.id,
+        limit=limit,
+        page_number=page_number,
+        order_by=order_by,
+        order_direction=order_direction,
     )
 
     # Convert entities to API schemas
diff --git a/agentex/src/api/routes/spans.py b/agentex/src/api/routes/spans.py
@@ -82,12 +82,18 @@ async def list_spans(
     trace_id: str | None = None,
     limit: int = 50,
     page_number: int = 1,
+    order_by: str | None = None,
+    order_direction: str = "desc",
 ) -> list[Span]:
     """
     List all spans for a given trace ID
     """
     logger.info(f"Listing spans for trace ID: {trace_id}")
     spans = await span_use_case.list(
-        trace_id=trace_id, limit=limit, page_number=page_number
+        trace_id=trace_id,
+        limit=limit,
+        page_number=page_number,
+        order_by=order_by,
+        order_direction=order_direction,
     )
     return [Span.model_validate(span) for span in spans]
diff --git a/agentex/src/api/routes/tasks.py b/agentex/src/api/routes/tasks.py
@@ -79,6 +79,8 @@ async def list_tasks(
     agent_name: str | None = None,
     limit: int = 50,
     page_number: int = 1,
+    order_by: str | None = None,
+    order_direction: str = "desc",
     relationships: Annotated[list[TaskRelationships], Query()] = None,
 ):
     """List all tasks."""
@@ -89,6 +91,8 @@ async def list_tasks(
         agent_name=agent_name,
         limit=limit,
         page_number=page_number,
+        order_by=order_by,
+        order_direction=order_direction,
         relationships=relationships,
     )
     return [TaskResponse.model_validate(task_entity) for task_entity in task_entities]
diff --git a/agentex/src/domain/repositories/agent_repository.py b/agentex/src/domain/repositories/agent_repository.py
@@ -28,13 +28,17 @@ async def list(
         filters: dict | None = None,
         limit: int | None = None,
         page_number: int | None = None,
+        order_by: str | None = None,
+        order_direction: str | None = None,
     ) -> list[AgentEntity]:
         """
         List agents with optional filtering.
 
         Args:
             filters: Dictionary of filters to apply. Currently supports:
                     - task_id: Filter agents by task ID using the join table
+            order_by: Field to order by
+            order_direction: Direction to order by (asc or desc)
         """
         query = select(AgentORM)
         if filters and "task_id" in filters:
@@ -43,7 +47,12 @@ async def list(
             ).where(TaskAgentORM.task_id == filters["task_id"])
         query = query.where(AgentORM.status != AgentStatus.DELETED)
         return await super().list(
-            filters=filters, query=query, limit=limit, page_number=page_number
+            filters=filters,
+            query=query,
+            limit=limit,
+            page_number=page_number,
+            order_by=order_by,
+            order_direction=order_direction,
         )
 
     @asynccontextmanager
diff --git a/agentex/src/domain/repositories/deployment_history_repository.py b/agentex/src/domain/repositories/deployment_history_repository.py
@@ -34,21 +34,30 @@ async def list(
         filters: dict | None = None,
         limit: int | None = None,
         page_number: int | None = None,
+        order_by: str | None = None,
+        order_direction: str | None = None,
     ) -> list[DeploymentHistoryEntity]:
         """
         List deployment history with optional filtering.
 
         Args:
             filters: Dictionary of filters to apply. Currently supports:
                     - agent_id: Filter agents by agent ID using the join table
+            order_by: Field to order by
+            order_direction: Order direction (asc or desc)
         """
         query = select(DeploymentHistoryORM)
         if filters and "agent_id" in filters:
             query = query.join(
                 AgentORM, AgentORM.id == DeploymentHistoryORM.agent_id
             ).where(AgentORM.id == filters["agent_id"])
         return await super().list(
-            filters=filters, query=query, limit=limit, page_number=page_number
+            filters=filters,
+            query=query,
+            limit=limit,
+            page_number=page_number,
+            order_by=order_by,
+            order_direction=order_direction,
         )
 
     async def get_last_deployment_for_agent(
diff --git a/agentex/src/domain/repositories/span_repository.py b/agentex/src/domain/repositories/span_repository.py
@@ -16,14 +16,22 @@ def __init__(
     ):
         super().__init__(async_read_write_session_maker, SpanORM, SpanEntity)
 
-    def list(
+    async def list(
         self,
         filters: dict[str, Any] | None = None,
         limit: int | None = None,
         page_number: int | None = None,
+        order_by: str | None = None,
+        order_direction: str | None = None,
     ) -> list[SpanEntity]:
-        return super().list(
-            filters, order_by="start_time", limit=limit, page_number=page_number
+        # Default to start_time if no order_by specified
+        effective_order_by = order_by or "start_time"
+        return await super().list(
+            filters=filters,
+            order_by=effective_order_by,
+            order_direction=order_direction,
+            limit=limit,
+            page_number=page_number,
         )
 
 
diff --git a/agentex/src/domain/services/task_service.py b/agentex/src/domain/services/task_service.py
@@ -181,6 +181,8 @@ async def list_tasks(
         id: str | list[str] | None = None,
         agent_id: str | None = None,
         agent_name: str | None = None,
+        order_by: str | None = None,
+        order_direction: str = "desc",
         relationships: list[TaskRelationships] | None = None,
     ) -> list[TaskEntity]:
         """
@@ -191,6 +193,8 @@ async def list_tasks(
             task_filters={"id": id} if id is not None else None,
             agent_id=agent_id,
             agent_name=agent_name,
+            order_by=order_by,
+            order_direction=order_direction,
             limit=limit,
             page_number=page_number,
             relationships=relationships,
diff --git a/agentex/src/domain/use_cases/agent_task_tracker_use_case.py b/agentex/src/domain/use_cases/agent_task_tracker_use_case.py
@@ -28,28 +28,25 @@ async def list(
         page_number: int,
         agent_id: str | None = None,
         task_id: str | None = None,
+        order_by: str | None = None,
+        order_direction: str = "desc",
     ) -> list[AgentTaskTrackerEntity]:
         """
         List agent task trackers.
         """
-        if agent_id and task_id:
-            return await self._tracker_repository.list(
-                filters={"agent_id": agent_id, "task_id": task_id},
-                limit=limit,
-                page_number=page_number,
-            )
-        elif agent_id:
-            return await self._tracker_repository.list(
-                filters={"agent_id": agent_id}, limit=limit, page_number=page_number
-            )
-        elif task_id:
-            return await self._tracker_repository.list(
-                filters={"task_id": task_id}, limit=limit, page_number=page_number
-            )
-        else:
-            return await self._tracker_repository.list(
-                limit=limit, page_number=page_number
-            )
+        filters = {}
+        if agent_id:
+            filters["agent_id"] = agent_id
+        if task_id:
+            filters["task_id"] = task_id
+
+        return await self._tracker_repository.list(
+            filters=filters if filters else None,
+            limit=limit,
+            page_number=page_number,
+            order_by=order_by,
+            order_direction=order_direction,
+        )
 
     async def update_agent_task_tracker(
         self,
diff --git a/agentex/src/domain/use_cases/agents_use_case.py b/agentex/src/domain/use_cases/agents_use_case.py
@@ -192,13 +192,19 @@ async def list(
         limit: int,
         page_number: int,
         task_id: str | None = None,
+        order_by: str | None = None,
+        order_direction: str = "desc",
         **filters,
     ) -> list[AgentEntity]:
         if task_id is not None:
             filters["task_id"] = task_id
 
         return await self.agent_repo.list(
-            filters=filters, limit=limit, page_number=page_number
+            filters=filters,
+            limit=limit,
+            page_number=page_number,
+            order_by=order_by,
+            order_direction=order_direction,
         )
 
 
diff --git a/agentex/src/domain/use_cases/deployment_history_use_case.py b/agentex/src/domain/use_cases/deployment_history_use_case.py
@@ -35,6 +35,8 @@ async def list_deployments(
         self,
         limit: int,
         page_number: int,
+        order_by: str | None = None,
+        order_direction: str = "desc",
         **filters,
     ) -> list[DeploymentHistoryEntity]:
         """
@@ -48,13 +50,19 @@ async def list_deployments(
             offset: Number of results to skip
             start_date: Filter deployments built after this date
             end_date: Filter deployments built before this date
+            order_by: Field to order by
+            order_direction: Order direction (asc or desc)
 
         Returns:
             List of deployment history entities
         """
         # Use the basic list method from the repository
         return await self.deployment_history_repository.list(
-            filters=filters, limit=limit, page_number=page_number
+            filters=filters,
+            limit=limit,
+            page_number=page_number,
+            order_by=order_by,
+            order_direction=order_direction,
         )
 
     async def get_last_deployment_for_agent(
diff --git a/agentex/src/domain/use_cases/spans_use_case.py b/agentex/src/domain/use_cases/spans_use_case.py
@@ -108,6 +108,8 @@ async def list(
         limit: int,
         page_number: int,
         trace_id: str | None = None,
+        order_by: str | None = None,
+        order_direction: str = "desc",
     ) -> list[SpanEntity]:
         """
         List all spans for a given trace ID
@@ -120,7 +122,11 @@ async def list(
         else:
             filters = None
         return await self.span_repo.list(
-            filters=filters, limit=limit, page_number=page_number
+            filters=filters,
+            limit=limit,
+            page_number=page_number,
+            order_by=order_by,
+            order_direction=order_direction,
         )
 
 
diff --git a/agentex/src/domain/use_cases/tasks_use_case.py b/agentex/src/domain/use_cases/tasks_use_case.py
@@ -69,6 +69,8 @@ async def list_tasks(
         id: str | list[str] | None = None,
         agent_id: str | None = None,
         agent_name: str | None = None,
+        order_by: str | None = None,
+        order_direction: str = "desc",
         relationships: list[TaskRelationships] | None = None,
     ) -> list[TaskEntity]:
         """List all tasks from repository"""
@@ -78,6 +80,8 @@ async def list_tasks(
             agent_name=agent_name,
             limit=limit,
             page_number=page_number,
+            order_by=order_by,
+            order_direction=order_direction,
             relationships=relationships,
         )
 
diff --git a/agentex/tests/integration/api/agent_task_tracker/test_agent_task_tracker_api.py b/agentex/tests/integration/api/agent_task_tracker/test_agent_task_tracker_api.py
diff --git a/agentex/tests/integration/api/agents/test_agents_crud.py b/agentex/tests/integration/api/agents/test_agents_crud.py
diff --git a/agentex/tests/integration/api/deployment_history/test_deployment_history_api.py b/agentex/tests/integration/api/deployment_history/test_deployment_history_api.py
diff --git a/agentex/tests/integration/api/spans/test_spans_api.py b/agentex/tests/integration/api/spans/test_spans_api.py
diff --git a/agentex/tests/integration/api/tasks/test_tasks_api.py b/agentex/tests/integration/api/tasks/test_tasks_api.py
