orchestrator-core 4.7.0rc1__tar.gz → 4.7.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orchestrator-core
-Version: 4.7.0rc1
+Version: 4.7.1
 Summary: This is the orchestrator workflow engine.
 Author-email: SURF <automation-beheer@surf.nl>
 Requires-Python: >=3.11,<3.15
@@ -31,13 +31,13 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: alembic==1.17.2
+Requires-Dist: alembic==1.18.1
 Requires-Dist: anyio>=3.7.0
 Requires-Dist: apscheduler>=3.11.0
 Requires-Dist: click==8.*
 Requires-Dist: deepmerge==2.0
 Requires-Dist: deprecated>=1.2.18
-Requires-Dist: fastapi~=0.124.0
+Requires-Dist: fastapi~=0.128.0
 Requires-Dist: fastapi-etag==0.4.0
 Requires-Dist: itsdangerous>=2.2.0
 Requires-Dist: jinja2==3.1.6
@@ -46,7 +46,7 @@ Requires-Dist: nwa-stdlib~=1.11.0
 Requires-Dist: oauth2-lib>=2.5.0
 Requires-Dist: orjson==3.11.5
 Requires-Dist: pgvector>=0.4.1
-Requires-Dist: prometheus-client==0.23.1
+Requires-Dist: prometheus-client==0.24.1
 Requires-Dist: psycopg2-binary==2.9.11
 Requires-Dist: pydantic-forms>=1.4.0
 Requires-Dist: pydantic-settings~=2.12.0
@@ -57,13 +57,13 @@ 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
-Requires-Dist: typer==0.20.0
-Requires-Dist: uvicorn[standard]~=0.38.0
+Requires-Dist: typer==0.21.1
+Requires-Dist: uvicorn[standard]~=0.40.0
 Requires-Dist: pydantic-ai-slim >=1.27.0 ; extra == "agent"
 Requires-Dist: ag-ui-protocol>=0.1.10 ; extra == "agent"
 Requires-Dist: litellm>=1.75.7 ; extra == "agent"

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

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

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.1}/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.1}/orchestrator/cli/scheduler.py

@@ -23,7 +23,7 @@ from orchestrator.schedules.scheduler import (
 )
 from orchestrator.schedules.service import (
     SCHEDULER_QUEUE,
-    add_scheduled_task_to_queue,
+    add_unique_scheduled_task_to_queue,
     workflow_scheduler_queue,
 )
 from orchestrator.schemas.schedules import APSchedulerJobCreate
@@ -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,16 @@ 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
+
+    This command is idempotent since 4.7.1 when the scheduler is running. The schedules are only
+    created when they do not already exist in the database.
+    """
     initial_schedules = [
         {
             "name": "Task Resume Workflows",
@@ -128,4 +171,4 @@ def load_initial_schedule() -> None:
         schedule["workflow_id"] = workflow.workflow_id
 
         typer.echo(f"Initial Schedule: {schedule}")
-        add_scheduled_task_to_queue(APSchedulerJobCreate(**schedule))  # type: ignore
+        add_unique_scheduled_task_to_queue(APSchedulerJobCreate(**schedule))  # type: ignore

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.1}/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.1}/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.1}/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.1}/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.1}/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.1/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.1}/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.1}/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.1}/orchestrator/schedules/service.py

@@ -66,17 +66,46 @@ def deserialize_payload(bytes_dump: bytes) -> APSchedulerJobs:
 def add_scheduled_task_to_queue(payload: APSchedulerJobs) -> None:
     """Create a scheduled task service function.
 
-    We need to create a apscheduler job, and put the workflow and schedule_id in
-    the linker table workflows_apscheduler_jobs.
+    We need to create, update or delete an apscheduler job, and put the
+    workflow and schedule_id in the linker table workflows_apscheduler_jobs.
+    This is done by adding a job to a redis queue which will be executed
+    when the scheduler runs.
 
     Args:
-        payload: APSchedulerJobCreate The scheduled task to create.
+        payload: APSchedulerJobs The scheduled task to create, update or delete
     """
     bytes_dump = serialize_payload(payload)
     redis_connection.lpush(SCHEDULER_QUEUE, bytes_dump)
     logger.info("Added scheduled task to queue.")
 
 
+def add_unique_scheduled_task_to_queue(payload: APSchedulerJobCreate) -> bool:
+    """Create a unique scheduled task service function.
+
+    Checks if the workflow is already scheduled before creating an apscheduler
+    job, and putting the workflow and schedule_id in the linker table
+    workflows_apscheduler_jobs.
+    This is done by adding a job to a redis queue which will be executed
+    when the scheduler runs.
+
+    This function is not safe for concurrent usage and when the scheduler is not
+    running, as there might be a race condition between adding a job and checking
+    if it already exists in the database.
+
+    Args:
+        payload: APSchedulerJobCreate The scheduled task to create.
+
+    Returns:
+        True when the scheduled task was added to the queue
+        False when the scheduled task was not added to the queue
+    """
+    if db.session.query(WorkflowApschedulerJob).filter_by(workflow_id=payload.workflow_id).all():
+        logger.info(f"Not adding existing workflow {payload.workflow_name} as scheduled task.")
+        return False
+    add_scheduled_task_to_queue(payload)
+    return True
+
+
 def get_linker_entries_by_schedule_ids(schedule_ids: list[str]) -> list[WorkflowApschedulerJob]:
     """Get linker table entries for multiple schedule IDs in a single query.
 

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.1}/orchestrator/schemas/search_requests.py

@@ -14,7 +14,7 @@
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from orchestrator.search.core.types import EntityType
+from orchestrator.search.core.types import EntityType, RetrieverType
 from orchestrator.search.filters import FilterTree
 from orchestrator.search.query.queries import SelectQuery
 
@@ -39,6 +39,10 @@ class SearchRequest(BaseModel):
         le=SelectQuery.MAX_LIMIT,
         description="Maximum number of search results to return.",
     )
+    retriever: RetrieverType | None = Field(
+        default=None,
+        description="Force a specific retriever type. If None, uses default routing logic.",
+    )
 
     model_config = ConfigDict(extra="forbid")
 
@@ -56,4 +60,5 @@ class SearchRequest(BaseModel):
             filters=self.filters,
             query_text=self.query,
             limit=self.limit,
+            retriever=self.retriever,
         )

{orchestrator_core-4.7.0rc1 → orchestrator_core-4.7.1}/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.1}/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.1}/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.1}/orchestrator/search/core/types.py

@@ -40,27 +40,28 @@ class SearchMetadata:
     @classmethod
     def structured(cls) -> "SearchMetadata":
         return cls(
-            search_type="structured", description="This search performs a filter-based search using structured queries."
+            search_type="structured",
+            description="This search performs a filter-based search using structured queries.",
         )
 
     @classmethod
     def fuzzy(cls) -> "SearchMetadata":
         return cls(
-            search_type="fuzzy",
+            search_type=RetrieverType.FUZZY.value,
             description="This search performs a trigram similarity search.",
         )
 
     @classmethod
     def semantic(cls) -> "SearchMetadata":
         return cls(
-            search_type="semantic",
+            search_type=RetrieverType.SEMANTIC.value,
             description="This search performs a vector similarity search, using L2 distance on embeddings with minimum distance scoring (normalized).",
         )
 
     @classmethod
     def hybrid(cls) -> "SearchMetadata":
         return cls(
-            search_type="hybrid",
+            search_type=RetrieverType.HYBRID.value,
             description="This search performs reciprocal rank fusion combining trigram similarity, word_similarity, and L2 vector distance.",
         )
 
@@ -109,6 +110,14 @@ class ActionType(str, Enum):
     AGGREGATE = "aggregate"  # Compute aggregations (sum, avg, etc.) over matching records.
 
 
+class RetrieverType(str, Enum):
+    """Defines available retriever types for search operations."""
+
+    FUZZY = "fuzzy"
+    SEMANTIC = "semantic"
+    HYBRID = "hybrid"
+
+
 class UIType(str, Enum):
     STRING = "string"
     NUMBER = "number"