orchestrator

目的

把使用者輸入送入系統路由（Router），依照 Router 決定的 pipeline 順序執行多個 LLM 模組（例如 EmotionSupport、Summary、Scheduling），並回傳整合後的最終輸出。

此文件描述 Orchestrator.forward 的實際輸入（以 src/time_compass/domain/orchestrator.py 為準）。

Input	Type	說明
user_input	string	使用者自由文字輸入（必填），作為 orchestrator.forward 的主要驅動內容。
dialog_history	string	對話/上下文歷史（選填），預設為空字串。

Orchestrator 的新責任： - Orchestrator 會先呼叫 Router，取得 pipeline 與初步回覆。 - 之後 Orchestrator 組裝一個完整的 InteractionContext（包含 dialog_history、user_input、pipeline、current_pipeline_index、previous_signature_output 等），傳遞給 pipeline 內的每個模組。 - 其他模組（如 EmotionSupport、Summary、Scheduling 等）都只接收 InteractionContext 作為輸入。 - 詳見 model/interaction_context.md

Workflow & Upstream Mapping

實作流程圖:

flowchart TD
N1["Client"] --> N2["Orchestrator"]
N2["Orchestrator"] --> N3["RouterModule"]
N3["RouterModule"] --> N4["Decide pipeline"]
N4["Decide pipeline"] --> N5["Loop over pipeline steps"]

N5 -->|"step == EmotionSupport"| N6["EmotionSupport"]
N5 -->|"step == Summary"| N7["Summary"]
N5 -->|"step == Scheduling"| N8["Scheduling"]

N6["EmotionSupport"] --> N9["Append output"] --> N5["Loop over pipeline steps"]
N7["Summary"] --> N9
N8["Scheduling"] --> N9

N5 -->|"no more steps"| N10["Compose final_reply"]
N10["Compose final_reply"] --> N11["Return RouterResponse"]

1. 呼叫端以 orch.forward(user_input, dialog_history) 呼叫 orchestrator。

2. Orchestrator 先呼叫 RouterModule，取得 pipeline 與 pipeline_description：

   router_response = self.router_module(
       dialog_history=dialog_history,
       user_input=user_input
   )
   

3. Orchestrator 根據 router_response 組裝 InteractionContext：

   • dialog_history、user_input 來自呼叫端
   • pipeline 來自 router_response
   • current_pipeline_index 由 orchestrator 控制
   • previous_signature_output 為前面模組的回覆彙整
   • 其他欄位如 time_interval_data 視需求補充

4. Orchestrator 依 pipeline 順序，將 InteractionContext 傳給每個模組（EmotionSupport、Summary、Scheduling 等），每個模組只需處理 context。

5. 每個模組的回傳值會被組成文字放入 final_reply，最後 router_response.final_reply 被設定並回傳。

6. 若需要 streaming 行為，專用的 build_streaming_orchestrator() 會建立一個 streamified orchestrator：

   stream_orch = dspy.streamify(
       orch, 
       stream_listeners=[...], 
       include_final_prediction_in_output_stream=True
   )
   

Streaming Listener 欄位建議

Orchestrator 若需支援 streaming，建議在 orchestrator.py 註冊下列 StreamListener，這些欄位皆為「給使用者」的主要回饋：

欄位名稱	說明	來源模組
pipeline_description	流程說明（1~3 句話）	Router
catch_and_rephrase	路由簡短回覆並重述使用者意圖	SchedulingRouter
ai_can_do	AI 可立即執行的動作摘要	SchedulingRouter
summary_text	區間回顧文字	Summary
draft_schedule	草案說明（含候選時段）	draft_plan
constraints_and_missing_info	草案/行動缺少資訊、假設、風險說明	draft_plan, draft_action
action_description	可執行的行動描述	draft_action
start_instructions	行動啟動說明	draft_action
questions	追問問題（根據缺資訊自動生成）	ask_question
next_steps_suggestion	追問後的下一步建議	ask_question

註：如有 EmotionSupport 等模組，請依各自 signature 文件補充 listener 欄位。