orchestrator-core 4.7.0rc1__tar.gz → 4.7.0rc2__tar.gz

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orchestrator-core
-Version: 4.7.0rc1
+Version: 4.7.0rc2
 Summary: This is the orchestrator workflow engine.
 Author-email: SURF <automation-beheer@surf.nl>
 Requires-Python: >=3.11,<3.15
@@ -57,8 +57,8 @@ Requires-Dist: pytz==2025.2
 Requires-Dist: redis==7.1.0
 Requires-Dist: semver==3.0.4
 Requires-Dist: sentry-sdk[fastapi]>=2.29.1
-Requires-Dist: sqlalchemy==2.0.44
-Requires-Dist: sqlalchemy-utils==0.42.0
+Requires-Dist: sqlalchemy==2.0.45
+Requires-Dist: sqlalchemy-utils==0.42.1
 Requires-Dist: strawberry-graphql>=0.281.0,<0.285.0
 Requires-Dist: structlog>=25.4.0
 Requires-Dist: tabulate==0.9.0

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/__init__.py

@@ -13,7 +13,7 @@
 
 """This is the orchestrator workflow engine."""
 
-__version__ = "4.7.0rc1"
+__version__ = "4.7.0rc2"
 
 
 from structlog import get_logger

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/app.py

@@ -57,7 +57,8 @@ from orchestrator.graphql.types import ScalarOverrideType, StrawberryModelType
 from orchestrator.log_config import LOGGER_OVERRIDES
 from orchestrator.metrics import ORCHESTRATOR_METRICS_REGISTRY, initialize_default_metrics
 from orchestrator.services.process_broadcast_thread import ProcessDataBroadcastThread
-from orchestrator.settings import AppSettings, ExecutorType, app_settings
+from orchestrator.settings import AppSettings, ExecutorType, app_settings, get_authorizers
+from orchestrator.utils.auth import Authorizer
 from orchestrator.version import GIT_COMMIT_HASH
 from orchestrator.websocket import init_websocket_manager
 from pydantic_forms.exception_handlers.fastapi import form_error_handler
@@ -311,6 +312,38 @@ class OrchestratorCore(FastAPI):
         """
         self.auth_manager.graphql_authorization = graphql_authorization_instance
 
+    def register_internal_authorize_callback(self, callback: Authorizer) -> None:
+        """Registers the authorize_callback for WFO's internal workflows and tasks.
+
+        Since RBAC policies are applied to workflows via decorator, this enables registration of callbacks
+        for workflows defined in orchestrator-core itself.
+        However, this assignment MUST be made before any workflows are run.
+
+        Args:
+            callback (Authorizer): The async Authorizer to run for the `authorize_callback` argument of internal workflows.
+
+        Returns:
+            None
+        """
+        authorizers = get_authorizers()
+        authorizers.internal_authorize_callback = callback
+
+    def register_internal_retry_auth_callback(self, callback: Authorizer) -> None:
+        """Registers the retry_auth_callback for WFO's internal workflows and tasks.
+
+        Since RBAC policies are applied to workflows via decorator, this enables registration of callbacks
+        for workflows defined in orchestrator-core itself.
+        However, this assignment MUST be made before any workflows are run.
+
+        Args:
+            callback (Authorizer): The async Authorizer to run for the `retry_auth_callback` argument of internal workflows.
+
+        Returns:
+            None
+        """
+        authorizers = get_authorizers()
+        authorizers.internal_retry_auth_callback = callback
+
 
 main_typer_app = typer.Typer()
 main_typer_app.add_typer(cli_app, name="orchestrator", help="The orchestrator CLI commands")

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/cli/scheduler.py

@@ -36,7 +36,13 @@ app: typer.Typer = typer.Typer()
 
 @app.command()
 def run() -> None:
-    """Start scheduler and loop eternally to keep thread alive."""
+    """Starts the scheduler in the foreground.
+
+    While running, this process will:
+
+      * Periodically wake up when the next schedule is due for execution, and run it
+      * Process schedule changes made through the schedule API
+    """
 
     def _get_scheduled_task_item_from_queue(redis_conn: Redis) -> tuple[str, bytes] | None:
         """Get an item from the Redis Queue for scheduler tasks."""
@@ -63,17 +69,45 @@ def run() -> None:
 
 @app.command()
 def show_schedule() -> None:
-    """Show the currently configured schedule.
+    """The `show-schedule` command shows an overview of the scheduled jobs."""
+    from rich.console import Console
+    from rich.table import Table
 
-    in cli underscore is replaced by a dash `show-schedule`
-    """
-    for task in get_all_scheduler_tasks():
-        typer.echo(f"[{task.id}] Next run: {task.next_run_time} | Trigger: {task.trigger}")
+    from orchestrator.schedules.service import get_linker_entries_by_schedule_ids
+
+    console = Console()
+
+    table = Table(title="Scheduled Tasks")
+    table.add_column("id", no_wrap=True)
+    table.add_column("name")
+    table.add_column("source")
+    table.add_column("next run time")
+    table.add_column("trigger")
+
+    scheduled_tasks = get_all_scheduler_tasks()
+    _schedule_ids = [task.id for task in scheduled_tasks]
+    api_managed = {str(i.schedule_id) for i in get_linker_entries_by_schedule_ids(_schedule_ids)}
+
+    for task in scheduled_tasks:
+        source = "API" if task.id in api_managed else "decorator"
+        run_time = str(task.next_run_time.replace(microsecond=0))
+        table.add_row(task.id, task.name, source, str(run_time), str(task.trigger))
+
+    console.print(table)
 
 
 @app.command()
 def force(task_id: str) -> None:
-    """Force the execution of (a) scheduler(s) based on a task_id."""
+    """Force the execution of (a) scheduler(s) based on a schedule ID.
+
+    Use the `show-schedule` command to determine the ID of the schedule to execute.
+
+    CLI Arguments:
+        ```sh
+        Arguments:
+            SCHEDULE_ID  ID of the schedule to execute
+        ```
+    """
     task = get_scheduler_task(task_id)
 
     if not task:
@@ -91,7 +125,18 @@ def force(task_id: str) -> None:
 
 @app.command()
 def load_initial_schedule() -> None:
-    """Load the initial schedule into the scheduler."""
+    """The `load-initial-schedule` command loads the initial schedule using the scheduler API.
+
+    The initial schedules are:
+      - Task Resume Workflows
+      - Task Clean Up Tasks
+      - Task Validate Subscriptions
+
+    !!! Warning
+        This command is not idempotent.
+
+        Please run `show-schedule` first to determine if the schedules already exist.
+    """
     initial_schedules = [
         {
             "name": "Task Resume Workflows",

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/graphql/schemas/process.py

@@ -89,8 +89,8 @@ class ProcessType:
         auth_resume, auth_retry = get_auth_callbacks(get_steps_to_evaluate_for_rbac(process), workflow)
 
         return FormUserPermissionsType(
-            retryAllowed=bool(auth_retry and auth_retry(oidc_user)),
-            resumeAllowed=bool(auth_resume and auth_resume(oidc_user)),
+            retryAllowed=bool(auth_retry and await auth_retry(oidc_user)),
+            resumeAllowed=bool(auth_resume and await auth_resume(oidc_user)),
         )
 
     @authenticated_field(description="Returns list of subscriptions of the process")  # type: ignore

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/llm_settings.py

@@ -34,7 +34,6 @@ EMBEDDING_DIMENSION_FIELD = Annotated[
 
 
 class LLMSettings(BaseSettings):
-
     # Feature flags for LLM functionality
     SEARCH_ENABLED: bool = False  # Enable search/indexing with embeddings
     AGENT_ENABLED: bool = False  # Enable agentic functionality

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/migrations/versions/schema/2020-10-19_a76b9185b334_add_generic_workflows_to_core.py

@@ -17,6 +17,7 @@ down_revision = "c112305b07d3"
 branch_labels = None
 depends_on = None
 
+# NOTE: this migration forgot to insert these workflows with is_task=true. Make sure to correct that if you copy this.
 workflows = [
     {"name": "modify_note", "description": "Modify Note", "workflow_id": uuid4(), "target": "MODIFY"},
     {"name": "task_clean_up_tasks", "description": "Clean up old tasks", "workflow_id": uuid4(), "target": "SYSTEM"},

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/migrations/versions/schema/2021-04-06_3c8b9185c221_add_validate_products_task.py

@@ -17,6 +17,7 @@ down_revision = "3323bcb934e7"
 branch_labels = None
 depends_on = None
 
+# NOTE: this migration forgot to insert these workflows with is_task=true. Make sure to correct that if you copy this.
 workflows = [
     {"name": "task_validate_products", "description": "Validate products", "workflow_id": uuid4(), "target": "SYSTEM"},
 ]

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/migrations/versions/schema/2025-11-18_961eddbd4c13_create_linker_table_workflow_apscheduler.py

@@ -17,7 +17,7 @@ down_revision = "850dccac3b02"
 branch_labels = None
 depends_on = None
 
-
+# NOTE: this migration forgot to insert these workflows with is_task=true. Make sure to correct that if you copy this.
 workflows = [
     {
         "name": "task_validate_subscriptions",

orchestrator_core-4.7.0rc2/orchestrator/migrations/versions/schema/2025-12-10_9736496e3eba_set_is_task_true_on_certain_tasks.py

@@ -0,0 +1,40 @@
+"""Set is_task=true on certain tasks.
+
+This is required to make them appear in the completed tasks in the UI, and for the cleanup task to be able to
+remove them.
+
+Revision ID: 9736496e3eba
+Revises: 961eddbd4c13
+Create Date: 2025-12-10 16:42:29.060382
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "9736496e3eba"
+down_revision = "961eddbd4c13"
+branch_labels = None
+depends_on = None
+
+task_names = [
+    # Added in a76b9185b334
+    "task_clean_up_tasks",
+    "task_resume_workflows",
+    # Added in 3c8b9185c221
+    "task_validate_products",
+    # Added in 961eddbd4c13
+    "task_validate_subscriptions",
+]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    query = sa.text("UPDATE workflows SET is_task=true WHERE name = :task_name and is_task=false")
+    for task_name in task_names:
+        conn.execute(query, parameters={"task_name": task_name})
+
+
+def downgrade() -> None:
+    pass  # Does not make sense to downgrade back to a 'bad' state.

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/schedules/__init__.py

@@ -15,7 +15,9 @@ import warnings
 from orchestrator.schedules.validate_products import validate_products
 
 warnings.warn(
-    "ALL_SCHEDULERS is deprecated; scheduling is now handled entirely through the scheduler API.",
+    "ALL_SCHEDULERS is deprecated and will be removed in 5.0.0. "
+    "Scheduling tasks can now be handled entirely through the API. "
+    "For more details, please consult https://workfloworchestrator.org/orchestrator-core/guides/upgrading/4.7/",
     DeprecationWarning,
     stacklevel=2,
 )

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/schedules/scheduling.py

@@ -23,7 +23,11 @@ F = TypeVar("F", bound=Callable[..., object])
 
 
 @deprecated(
-    reason="We changed from scheduler to apscheduler which has its own decoractor, use `@scheduler.scheduled_job()` from `from orchestrator.scheduling.scheduler import scheduler`"
+    reason=(
+        "Scheduling tasks with a decorator is deprecated in favor of using the API. "
+        "This decorator will be removed in 5.0.0. "
+        "For more details, please consult https://workfloworchestrator.org/orchestrator-core/guides/upgrading/4.7/"
+    )
 )
 def scheduler(
     name: str,

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/search/agent/prompts.py

@@ -26,7 +26,7 @@ logger = structlog.get_logger(__name__)
 
 async def get_base_instructions() -> str:
     return dedent(
-        """
+        f"""
         You are an expert assistant designed to find relevant information by building and running database queries.
 
         ---
@@ -50,17 +50,21 @@ async def get_base_instructions() -> str:
 
         Follow these steps:
 
-        1.  **Set Context**: Call `start_new_search` with appropriate entity_type and action
+        1.  **Set Context**: Call `start_new_search` with appropriate entity_type and action:
+            - `action={ActionType.SELECT.value}` for finding/searching entities
+            - `action={ActionType.COUNT.value}` for counting (e.g., "how many", "count by status", "monthly growth")
+            - `action={ActionType.AGGREGATE.value}` for numeric operations (SUM, AVG, MIN, MAX of specific fields)
         2.  **Set Filters** (if needed): Discover paths, build FilterTree, call `set_filter_tree`
             - IMPORTANT: Temporal constraints like "in 2025", "in January", "between X and Y" require filters on datetime fields
             - Filters restrict WHICH records to include; grouping controls HOW to aggregate them
-        3.  **Set Grouping/Aggregations** (for COUNT/AGGREGATE):
+        3.  **Set Grouping/Aggregations** (for {ActionType.COUNT.value}/{ActionType.AGGREGATE.value}):
             - For temporal grouping (per month, per year, per day, etc.): Use `set_temporal_grouping`
             - For regular grouping (by status, by name, etc.): Use `set_grouping`
-            - For aggregations: Use `set_aggregations`
+            - For {ActionType.AGGREGATE.value} action ONLY: Use `set_aggregations` to specify what to compute (SUM, AVG, etc.)
+            - For {ActionType.COUNT.value} action: Do NOT call `set_aggregations` (counting is automatic)
         4.  **Execute**:
-            - For SELECT action: Call `run_search()`
-            - For COUNT/AGGREGATE actions: Call `run_aggregation()`
+            - For {ActionType.SELECT.value} action: Call `run_search()`
+            - For {ActionType.COUNT.value}/{ActionType.AGGREGATE.value} actions: Call `run_aggregation()`
 
         After search execution, follow the dynamic instructions based on the current state.
 

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/search/agent/tools.py

@@ -16,6 +16,7 @@ from typing import Any, cast
 
 import structlog
 from ag_ui.core import EventType, StateSnapshotEvent
+from pydantic import ValidationError
 from pydantic_ai import RunContext
 from pydantic_ai.ag_ui import StateDeps
 from pydantic_ai.exceptions import ModelRetry
@@ -39,13 +40,15 @@ from orchestrator.search.filters import FilterTree
 from orchestrator.search.query import engine
 from orchestrator.search.query.exceptions import PathNotFoundError, QueryValidationError
 from orchestrator.search.query.export import fetch_export_data
+from orchestrator.search.query.mixins import OrderBy
 from orchestrator.search.query.queries import AggregateQuery, CountQuery, Query, SelectQuery
 from orchestrator.search.query.results import AggregationResponse, AggregationResult, ExportData, VisualizationType
 from orchestrator.search.query.state import QueryState
 from orchestrator.search.query.validation import (
     validate_aggregation_field,
-    validate_filter_path,
     validate_filter_tree,
+    validate_grouping_fields,
+    validate_order_by_fields,
     validate_temporal_grouping_field,
 )
 from orchestrator.settings import app_settings
@@ -404,20 +407,30 @@ async def prepare_export(
 async def set_grouping(
     ctx: RunContext[StateDeps[SearchState]],
     group_by_paths: list[str],
+    order_by: list[OrderBy] | None = None,
 ) -> StateSnapshotEvent:
     """Set which field paths to group results by for aggregation.
 
     Only used with COUNT or AGGREGATE actions. Paths must exist in the schema; use discover_filter_paths to verify.
+    Optionally specify ordering for the grouped results.
+
+    For order_by: You can order by grouping field paths OR aggregation aliases (e.g., 'count').
+    Grouping field paths will be validated; aggregation aliases cannot be validated until execution.
     """
-    for path in group_by_paths:
-        field_type = validate_filter_path(path)
-        if field_type is None:
-            raise ModelRetry(
-                f"Path '{path}' not found in database schema. "
-                f"Use discover_filter_paths(['{path.split('.')[-1]}']) to find valid paths."
-            )
+    try:
+        validate_grouping_fields(group_by_paths)
+        validate_order_by_fields(order_by)
+    except PathNotFoundError as e:
+        raise ModelRetry(f"{str(e)} Use discover_filter_paths to find valid paths.")
 
-    ctx.deps.state.query = cast(Query, ctx.deps.state.query).model_copy(update={"group_by": group_by_paths})
+    update_dict: dict[str, Any] = {"group_by": group_by_paths}
+    if order_by is not None:
+        update_dict["order_by"] = order_by
+
+    try:
+        ctx.deps.state.query = cast(Query, ctx.deps.state.query).model_copy(update=update_dict)
+    except ValidationError as e:
+        raise ModelRetry(str(e))
 
     return StateSnapshotEvent(
         type=EventType.STATE_SNAPSHOT,
@@ -434,16 +447,26 @@ async def set_aggregations(
     """Define what aggregations to compute over the matching records.
 
     Only used with AGGREGATE action. See Aggregation model (CountAggregation, FieldAggregation) for structure and field requirements.
+
     """
     # Validate field paths for FieldAggregations
     try:
         for agg in aggregations:
             if isinstance(agg, FieldAggregation):
                 validate_aggregation_field(agg.type, agg.field)
-    except ValueError as e:
-        raise ModelRetry(f"{str(e)} Use discover_filter_paths to find valid paths.")
+    except PathNotFoundError as e:
+        raise ModelRetry(
+            f"{str(e)} "
+            f"You MUST call discover_filter_paths first to find valid fields. "
+            f"If the field truly doesn't exist, inform the user that this data is not available."
+        )
+    except QueryValidationError as e:
+        raise ModelRetry(f"{str(e)}")
 
-    ctx.deps.state.query = cast(Query, ctx.deps.state.query).model_copy(update={"aggregations": aggregations})
+    try:
+        ctx.deps.state.query = cast(Query, ctx.deps.state.query).model_copy(update={"aggregations": aggregations})
+    except ValidationError as e:
+        raise ModelRetry(str(e))
 
     return StateSnapshotEvent(
         type=EventType.STATE_SNAPSHOT,
@@ -456,19 +479,36 @@ async def set_aggregations(
 async def set_temporal_grouping(
     ctx: RunContext[StateDeps[SearchState]],
     temporal_groups: list[TemporalGrouping],
+    cumulative: bool = False,
+    order_by: list[OrderBy] | None = None,
 ) -> StateSnapshotEvent:
     """Set temporal grouping to group datetime fields by time periods.
 
     Only used with COUNT or AGGREGATE actions. See TemporalGrouping model for structure, periods, and examples.
+    Optionally enable cumulative aggregations (running totals) and specify ordering.
+
+    For order_by: You can order by temporal field paths OR aggregation aliases (e.g., 'count').
+    Temporal field paths will be validated; aggregation aliases cannot be validated until execution.
     """
-    # Validate that fields exist and are datetime types
     try:
         for tg in temporal_groups:
             validate_temporal_grouping_field(tg.field)
-    except ValueError as e:
+        validate_order_by_fields(order_by)
+    except PathNotFoundError as e:
+        raise ModelRetry(f"{str(e)} Use discover_filter_paths to find valid paths.")
+    except QueryValidationError as e:
         raise ModelRetry(f"{str(e)} Use discover_filter_paths to find datetime fields.")
 
-    ctx.deps.state.query = cast(Query, ctx.deps.state.query).model_copy(update={"temporal_group_by": temporal_groups})
+    update_dict: dict[str, Any] = {"temporal_group_by": temporal_groups}
+    if cumulative:
+        update_dict["cumulative"] = cumulative
+    if order_by is not None:
+        update_dict["order_by"] = order_by
+
+    try:
+        ctx.deps.state.query = cast(Query, ctx.deps.state.query).model_copy(update=update_dict)
+    except ValidationError as e:
+        raise ModelRetry(str(e))
 
     return StateSnapshotEvent(
         type=EventType.STATE_SNAPSHOT,

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/search/aggregations/base.py

@@ -61,6 +61,11 @@ class TemporalGrouping(BaseModel):
         },
     )
 
+    @property
+    def alias(self) -> str:
+        """Return the SQL-friendly alias for this temporal grouping."""
+        return f"{BaseAggregation.field_to_alias(self.field)}_{self.period.value}"
+
     def get_pivot_fields(self) -> list[str]:
         """Return fields that need to be pivoted for this temporal grouping."""
         return [self.field]
@@ -83,8 +88,7 @@ class TemporalGrouping(BaseModel):
         col = getattr(pivot_cte_columns, field_alias)
         truncated_col = func.date_trunc(self.period.value, cast(col, TIMESTAMP(timezone=True)))
 
-        # Column name without prefix
-        col_name = f"{field_alias}_{self.period.value}"
+        col_name = self.alias
         select_col = truncated_col.label(col_name)
         return select_col, truncated_col, col_name
 

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/search/query/builder.py

@@ -25,6 +25,7 @@ from orchestrator.db.models import AiSearchIndex
 from orchestrator.search.aggregations import AggregationType, BaseAggregation, CountAggregation
 from orchestrator.search.core.types import EntityType, FieldType, FilterOp, UIType
 from orchestrator.search.filters import LtreeFilter
+from orchestrator.search.query.mixins import OrderDirection
 from orchestrator.search.query.queries import AggregateQuery, CountQuery, Query
 
 
@@ -181,7 +182,8 @@ def _build_pivot_cte(base_query: Select, pivot_fields: list[str]) -> CTE:
 
 
 def _build_grouping_columns(
-    query: CountQuery | AggregateQuery, pivot_cte: CTE
+    query: CountQuery | AggregateQuery,
+    pivot_cte: CTE,
 ) -> tuple[list[Any], list[Any], list[str]]:
     """Build GROUP BY columns and their SELECT columns.
 
@@ -244,6 +246,76 @@ def _build_aggregation_columns(query: CountQuery | AggregateQuery, pivot_cte: CT
     return [count_agg.to_expression(pivot_cte.c.entity_id)]
 
 
+def _apply_cumulative_aggregations(
+    stmt: Select,
+    query: CountQuery | AggregateQuery,
+    group_column_names: list[str],
+    aggregation_columns: list[Label],
+) -> Select:
+    """Add cumulative aggregation columns."""
+
+    # At this point, cumulative validation has already happened at query build time
+    # in GroupingMixin.validate_grouping_constraints, so we know:
+    # temporal_group_by exists and has exactly 1 element when cumulative=True
+    if not query.cumulative or not aggregation_columns or not query.temporal_group_by:
+        return stmt
+
+    temporal_alias = query.temporal_group_by[0].alias
+
+    base_subquery = stmt.subquery()
+    partition_cols = [base_subquery.c[name] for name in group_column_names if name != temporal_alias]
+    order_col = base_subquery.c[temporal_alias]
+
+    base_columns = [base_subquery.c[col] for col in base_subquery.c.keys()]
+
+    cumulative_columns = []
+    for agg_col in aggregation_columns:
+        cumulative_alias = f"{agg_col.key}_cumulative"
+        over_kwargs: dict[str, Any] = {"order_by": order_col}
+        if partition_cols:
+            over_kwargs["partition_by"] = partition_cols
+        cumulative_expr = func.sum(base_subquery.c[agg_col.key]).over(**over_kwargs).label(cumulative_alias)
+        cumulative_columns.append(cumulative_expr)
+
+    return select(*(base_columns + cumulative_columns)).select_from(base_subquery)
+
+
+def _apply_ordering(
+    stmt: Select,
+    query: CountQuery | AggregateQuery,
+    group_column_names: list[str],
+) -> Select:
+    """Apply ordering instructions to the SELECT statement."""
+    columns_by_key = {col.key: col for col in stmt.selected_columns}
+
+    if query.order_by:
+        order_expressions = []
+        for instruction in query.order_by:
+            # 1) exact match
+            col = columns_by_key.get(instruction.field)
+            if col is None:
+                # 2) temporal alias,
+                for tg in query.temporal_group_by or []:
+                    if instruction.field == tg.field or instruction.field == tg.alias:
+                        col = columns_by_key.get(tg.alias)
+                        if col is not None:
+                            break
+                if col is None:
+                    # 3) normalized field path
+                    col = columns_by_key.get(BaseAggregation.field_to_alias(instruction.field))
+            if col is None:
+                raise ValueError(f"Cannot order by '{instruction.field}'; column not found.")
+            order_expressions.append(col.desc() if instruction.direction == OrderDirection.DESC else col.asc())
+        return stmt.order_by(*order_expressions)
+
+    if query.temporal_group_by:
+        # Default ordering by all grouping columns (ascending)
+        order_expressions = [columns_by_key[col_name].asc() for col_name in group_column_names]
+        return stmt.order_by(*order_expressions)
+
+    return stmt
+
+
 def build_simple_count_query(base_query: Select) -> Select:
     """Build a simple count query without grouping.
 
@@ -282,7 +354,7 @@ def build_aggregation_query(query: CountQuery | AggregateQuery, base_query: Sele
     if group_cols:
         stmt = stmt.group_by(*group_cols)
 
-    if query.temporal_group_by:
-        stmt = stmt.order_by(*group_cols)
+    stmt = _apply_cumulative_aggregations(stmt, query, group_col_names, agg_cols)
+    stmt = _apply_ordering(stmt, query, group_col_names)
 
     return stmt, group_col_names

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.0rc2}/orchestrator/search/query/mixins.py

@@ -1,6 +1,8 @@
 import uuid
+from enum import Enum
+from typing import Self
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 from orchestrator.search.aggregations import Aggregation, TemporalGrouping
 
@@ -8,9 +10,28 @@ __all__ = [
     "SearchMixin",
     "GroupingMixin",
     "AggregationMixin",
+    "OrderBy",
+    "OrderDirection",
 ]
 
 
+class OrderDirection(str, Enum):
+    """Sorting direction for aggregation results."""
+
+    ASC = "asc"
+    DESC = "desc"
+
+
+class OrderBy(BaseModel):
+    """Ordering descriptor for aggregation responses."""
+
+    field: str = Field(description="Grouping or aggregation field/alias to order by.")
+    direction: OrderDirection = Field(
+        default=OrderDirection.ASC,
+        description="Sorting direction (asc or desc).",
+    )
+
+
 class SearchMixin(BaseModel):
     """Mixin providing text search capability.
 
@@ -59,6 +80,37 @@ class GroupingMixin(BaseModel):
         default=None,
         description="Temporal grouping specifications (group by month, year, etc.)",
     )
+    cumulative: bool = Field(
+        default=False,
+        description="Enable cumulative aggregations when temporal grouping is present.",
+    )
+    order_by: list[OrderBy] | None = Field(
+        default=None,
+        description="Ordering instructions for grouped aggregation results.",
+    )
+
+    @model_validator(mode="after")
+    def validate_grouping_constraints(self) -> Self:
+        """Validate cross-field constraints for grouping features."""
+        if self.order_by and not self.group_by and not self.temporal_group_by:
+            raise ValueError(
+                "order_by requires at least one grouping field (group_by or temporal_group_by). "
+                "Ordering only applies to grouped aggregation results."
+            )
+
+        if self.cumulative:
+            if not self.temporal_group_by:
+                raise ValueError(
+                    "cumulative requires at least one temporal grouping (temporal_group_by). "
+                    "Cumulative aggregations compute running totals over time."
+                )
+            if len(self.temporal_group_by) > 1:
+                raise ValueError(
+                    "cumulative currently supports only a single temporal grouping. "
+                    "Multiple temporal dimensions with running totals are not yet supported."
+                )
+
+        return self
 
     def get_pivot_fields(self) -> list[str]:
         """Get all fields needed for EAV pivot from grouping.
@@ -82,7 +134,10 @@ class AggregationMixin(BaseModel):
     Used by AGGREGATE queries to define what statistics to compute.
     """
 
-    aggregations: list[Aggregation] = Field(description="Aggregations to compute (SUM, AVG, MIN, MAX, COUNT)")
+    aggregations: list[Aggregation] = Field(
+        description="Aggregations to compute (SUM, AVG, MIN, MAX, COUNT)",
+        min_length=1,
+    )
 
     def get_aggregation_pivot_fields(self) -> list[str]:
         """Get fields needed for EAV pivot from aggregations.