feat(query): add temporal_relation and evidence_request plan steps

pyproject.toml

@@ -161,3 +161,8 @@ torchaudio = [
 name = "pytorch-cpu"
 url = "https://download.pytorch.org/whl/cpu"
 explicit = true
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

src/vidxp/application_models.py

@@ -1044,18 +1044,48 @@ def _unique_modalities(
         return values
 
 
+class OccurrenceMode(StrEnum):
+    first = "first"
+    best = "best"
+    all = "all"
+
+
 class SearchMomentsPlanStep(ApplicationModel):
     kind: Literal["search_moments"] = "search_moments"
     modality: Identifier
     query: SearchQuery
+    occurrence_mode: OccurrenceMode = OccurrenceMode.best
 
 
 class ActorOverviewPlanStep(ApplicationModel):
     kind: Literal["actor_overview"] = "actor_overview"
 
 
+class TemporalRelation(StrEnum):
+    before = "before"
+    after = "after"
+    during = "during"
+
+
+class TemporalRelationPlanStep(ApplicationModel):
+    kind: Literal["temporal_relation"] = "temporal_relation"
+    relation: TemporalRelation
+    reference_query: SearchQuery
+    target_modality: Identifier
+    target_query: SearchQuery
+
+
+class EvidenceRequestPlanStep(ApplicationModel):
+    kind: Literal["evidence_request"] = "evidence_request"
+    delivery_mode: EvidenceDeliveryMode
+    include_board: bool = False
+
+
 QueryPlanStep = Annotated[
-    SearchMomentsPlanStep | ActorOverviewPlanStep,
+    SearchMomentsPlanStep
+    | ActorOverviewPlanStep
+    | TemporalRelationPlanStep
+    | EvidenceRequestPlanStep,
     Field(discriminator="kind"),
 ]
 
@@ -1068,6 +1098,8 @@ class QueryPlanningRequest(ApplicationModel):
     question: SearchQuery
     allowed_modalities: tuple[Identifier, ...]
     actor_overview_allowed: bool = False
+    temporal_relations_allowed: bool = False
+    evidence_requests_allowed: bool = False
 
 
 class QueryModelIdentity(ApplicationModel):

src/vidxp/query_service.py

@@ -5,8 +5,10 @@
 
 from vidxp.application_models import (
     ActorEvidence,
+    ActorOverviewPlanStep,
     DraftAnswer,
     Evidence,
+    EvidenceRequestPlanStep,
     FusedSearchResult,
     GroundedClaim,
     IndexSnapshotReference,
@@ -18,7 +20,7 @@
     QuerySynthesisRequest,
     QueryVideoCommand,
     SearchMomentsPlanStep,
-    ActorOverviewPlanStep,
+    TemporalRelationPlanStep,
 )
 from vidxp.capabilities.actor.schemas import ActorClusterSummary
 from vidxp.ports import QueryModelPort, QueryProviderError
@@ -39,6 +41,8 @@ def _default_plan(
     *,
     search_modalities: tuple[str, ...],
     actor_overview: bool,
+    temporal_relations: bool = False,
+    evidence_requests: bool = False,
 ) -> QueryPlan:
     steps = [
         SearchMomentsPlanStep(
@@ -57,6 +61,8 @@ def _valid_plan(
     *,
     search_modalities: tuple[str, ...],
     actor_overview: bool,
+    temporal_relations: bool = False,
+    evidence_requests: bool = False,
 ) -> bool:
     searches = [
         step.modality
@@ -66,6 +72,16 @@ def _valid_plan(
     actor_steps = sum(
         isinstance(step, ActorOverviewPlanStep) for step in plan.steps
     )
+    temporal_steps = sum(
+        isinstance(step, TemporalRelationPlanStep) for step in plan.steps
+    )
+    evidence_steps = sum(
+        isinstance(step, EvidenceRequestPlanStep) for step in plan.steps
+    )
+    if not temporal_relations and temporal_steps > 0:
+        return False
+    if not evidence_requests and evidence_steps > 0:
+        return False
     return (
         len(searches) == len(set(searches))
         and set(searches) == set(search_modalities)
@@ -85,11 +101,15 @@ def plan(
         *,
         search_modalities: tuple[str, ...],
         actor_overview: bool,
+        temporal_relations: bool = False,
+        evidence_requests: bool = False,
     ) -> tuple[QueryPlan, str | None]:
         fallback = _default_plan(
             command,
             search_modalities=search_modalities,
             actor_overview=actor_overview,
+            temporal_relations=temporal_relations,
+            evidence_requests=evidence_requests,
         )
         if self.model is None:
             return fallback, "query_model_not_configured"
@@ -99,6 +119,8 @@ def plan(
                     question=command.question,
                     allowed_modalities=search_modalities,
                     actor_overview_allowed=actor_overview,
+                    temporal_relations_allowed=temporal_relations,
+                    evidence_requests_allowed=evidence_requests,
                 )
             )
         except QueryProviderError:
@@ -107,6 +129,8 @@ def plan(
             proposed,
             search_modalities=search_modalities,
             actor_overview=actor_overview,
+            temporal_relations=temporal_relations,
+            evidence_requests=evidence_requests,
         ):
             return fallback, "query_plan_rejected"
         return proposed, None