From 40393d81f8fadbcca123be2f81e9a740c4ff3b74 Mon Sep 17 00:00:00 2001
From: Woody <woody.ck.tse@gmail.com>
Date: Sun, 26 Apr 2026 23:28:19 +0800
Subject: [PATCH] feat(models): add SubQuestionSources model and per-sub-q
 history fields

Add SubQuestionSources, SubQuestionResult, GeneratingSubquestionEvent Pydantic models for the new per-sub-question response format. Add chunks_retrieved_per_subq_count and chunks_filtered_per_subq_count optional fields to QueryHistoryRecord and QueryHistoryDetail for per-sub-question chunk count tracking.

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 backend/app/models/history.py |  4 ++++
 backend/app/models/query.py   | 30 ++++++++++++++++++++++++++++--
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/backend/app/models/history.py b/backend/app/models/history.py
index 7ea028a..d409228 100644
--- a/backend/app/models/history.py
+++ b/backend/app/models/history.py
@@ -22,6 +22,8 @@ class QueryHistoryRecord(BaseModel):
     final_answer: Optional[str] = None
     sources: Optional[str] = None
     profile_used: Optional[str] = None
+    chunks_retrieved_per_subq_count: Optional[str] = None
+    chunks_filtered_per_subq_count: Optional[str] = None
 
 
 class QueryHistorySummary(BaseModel):
@@ -53,6 +55,8 @@ class QueryHistoryDetail(BaseModel):
     final_answer: Optional[str] = None
     sources: Optional[str] = None
     profile_used: Optional[str] = None
+    chunks_retrieved_per_subq_count: Optional[str] = None
+    chunks_filtered_per_subq_count: Optional[str] = None
     created_at: str
 
 
diff --git a/backend/app/models/query.py b/backend/app/models/query.py
index ea091eb..beb4d35 100644
--- a/backend/app/models/query.py
+++ b/backend/app/models/query.py
@@ -9,10 +9,23 @@ class QueryRequest(BaseModel):
     question: str
 
 
+class SubQuestionSources(BaseModel):
+    sub_question_index: int
+    sub_question_text: str
+    sources: List[SourceMetadata]
+
+
+class SubQuestionResult(BaseModel):
+    sub_question_index: int
+    sub_question_text: str
+    answer_section: str
+
+
 class QueryResponse(BaseModel):
     extracted_questions: List[str]
     answer: str
-    sources: List[SourceMetadata]
+    sub_question_sources: List[SubQuestionSources] = []
+    sources: List[SourceMetadata] = []
 
 
 class DecomposedEvent(BaseModel):
@@ -28,10 +41,22 @@ class FilteringEvent(BaseModel):
     phase: Literal["filtering"]
 
 
+class GeneratingEvent(BaseModel):
+    phase: Literal["generating"]
+
+
+class GeneratingSubquestionEvent(BaseModel):
+    phase: Literal["generating_subquestion"]
+    sub_question_index: int
+    sub_question_text: str
+    answer_section: str = ""
+
+
 class CompletedEvent(BaseModel):
     phase: Literal["completed"]
     answer: str
-    sources: List[SourceMetadata]
+    sub_question_sources: List[SubQuestionSources] = []
+    sources: List[SourceMetadata] = []
 
 
 class ErrorEvent(BaseModel):
@@ -41,5 +66,6 @@ class ErrorEvent(BaseModel):
 
 StreamingQueryEvent = Union[
     DecomposedEvent, RetrievingEvent, FilteringEvent,
+    GeneratingEvent, GeneratingSubquestionEvent,
     CompletedEvent, ErrorEvent
 ]