Kommentare zur übersicht

math-tutor/backend/app/deterministic_services/orchestrators/orchestrator_base.py

@@ -34,6 +34,10 @@ def is_new_chat(messages: list[dict]) -> bool:
     return not any(m.get("role") == "assistant" for m in messages)
 
 
+# ---
+# Timekeeping
+# ---
+
 def _utc_now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
@@ -48,26 +52,6 @@ def _finish_timing(started_perf: float) -> tuple[str, float]:
     return finished_at, duration_ms
 
 
-def append_tool_log(
-    tool_log: list[dict],
-    name: str,
-    args: dict,
-    response: object,
-    *,
-    started_at: str | None = None,
-    finished_at: str | None = None,
-    duration_ms: float | None = None,
-) -> None:
-    entry = {"name": name, "arguments": args, "response": response}
-    if started_at is not None:
-        entry["started_at"] = started_at
-    if finished_at is not None:
-        entry["finished_at"] = finished_at
-    if duration_ms is not None:
-        entry["duration_ms"] = duration_ms
-    tool_log.append(entry)
-
-
 def log_timed_call(
     tool_log: list[dict],
     name: str,
@@ -102,6 +86,33 @@ def log_timed_call(
     )
     return response
 
+# ---
+# Toolcalling
+# ---
+
+def append_tool_log(
+    tool_log: list[dict],
+    name: str,
+    args: dict,
+    response: object,
+    *,
+    started_at: str | None = None,
+    finished_at: str | None = None,
+    duration_ms: float | None = None,
+) -> None:
+    entry = {"name": name, "arguments": args, "response": response}
+    if started_at is not None:
+        entry["started_at"] = started_at
+    if finished_at is not None:
+        entry["finished_at"] = finished_at
+    if duration_ms is not None:
+        entry["duration_ms"] = duration_ms
+    tool_log.append(entry)
+
+
+# ---
+# LLM Nachricht entpacken
+# ---
 
 def extract_user_messages(messages: list[dict]) -> list[str]:
     user_contents: list[str] = []
@@ -112,6 +123,9 @@ def extract_user_messages(messages: list[dict]) -> list[str]:
                 user_contents.append(content)
     return user_contents
 
+# --
+# Konext
+# --
 
 def retrieve_context(
     query_text: str, pg_url: str | None = None
@@ -158,6 +172,9 @@ def bootstrap_retrieval(sheet: dict, query_text: str, tool_log: list[dict]) -> N
     )
     context_store.update_retrieval_context(sheet, sources)
 
+# -- 
+# Chat Status
+# --
 
 def init_chat_state(messages: list[dict], draft: str | None = None) -> ChatState:
     if not messages:
@@ -186,6 +203,10 @@ def init_chat_state(messages: list[dict], draft: str | None = None) -> ChatState
     )
 
 
+# -- 
+# Ausgabe
+# --
+
 def finalize_response(state: ChatState, reply: str | None) -> dict:
     if not reply:
         reply = "Dazu steht nichts im Material"
@@ -204,6 +225,10 @@ def finalize_response(state: ChatState, reply: str | None) -> dict:
     return {"reply": reply, "sources": state.sheet.get("sources", []), "tool_log": state.tool_log}
 
 
+# --
+# gesamtablauf einens Chats
+# --
+
 def run_chat_common(
     messages: list[dict],
     draft: str | None,

math-tutor/backend/app/deterministic_services/orchestrators/orchestrator_qa.py

@@ -4,14 +4,17 @@ from app.LLM_services import qa_LLM
 from app.deterministic_services import context_store
 from app.deterministic_services.orchestrators import orchestrator_base as base
 
+# beim ersten Aufruf
 
 def _on_bootstrap(state: base.ChatState, query_text: str) -> None:
     base.bootstrap_retrieval(state.sheet, query_text, state.tool_log)
 
+# Sonstiges bei jedem Aufruf
 
 def _on_turn_logic(state: base.ChatState) -> None:
     return None
 
+# Antwort generieren
 
 def _on_build_reply(state: base.ChatState) -> str | None:
     args = {

math-tutor/backend/app/deterministic_services/orchestrators/orchestrator_task.py

@@ -87,17 +87,20 @@ def _retrieve_context_for_task(state: base.ChatState, query_text: str) -> None:
         _retrieve,
     )
 
+# beim ersten Aufruf
 
 def _on_bootstrap(state: base.ChatState, query_text: str) -> None:
     base.bootstrap_retrieval(state.sheet, query_text, state.tool_log)
     _ensure_context_task_fields(state, query_text)
     _retrieve_context_for_task(state, query_text)
 
+# Sonstiges bei jedem Aufruf
 
 def _on_turn_logic(state: base.ChatState) -> None:
     _ensure_context_task_fields(state, state.last_user)
     _retrieve_context_for_task(state, state.last_user)
 
+# Antwort generieren
 
 def _on_build_reply(state: base.ChatState) -> str | None:
     store_new = context_store.context_store_new

math-tutor/backend/app/deterministic_services/orchestrators/orchestrator_tutor.py

@@ -4,6 +4,7 @@ from app.LLM_services import decision_LLM, open_hint_LLM, math_intent_LLM, solve
 from app.deterministic_services import context_store
 from app.deterministic_services.orchestrators import orchestrator_base as base
 
+# beim ersten Aufruf
 
 def _on_bootstrap(state: base.ChatState, query_text: str) -> None:
     base.bootstrap_retrieval(state.sheet, query_text, state.tool_log)
@@ -16,6 +17,7 @@ def _on_bootstrap(state: base.ChatState, query_text: str) -> None:
     if math_solution:
         context_store.add_math_solution(state.sheet, math_solution)
 
+# Sonstiges bei jedem Aufruf
 
 def _on_turn_logic(state: base.ChatState) -> None:
     sheet_text = context_store.format_sheet(state.sheet)
@@ -42,6 +44,7 @@ def _on_turn_logic(state: base.ChatState) -> None:
         full_query = "\n".join(base.extract_user_messages(state.messages))
         _on_bootstrap(state, full_query)
 
+# Antwort generieren
 
 def _on_build_reply(state: base.ChatState) -> str | None:
     history_turns = context_store.get_history_turns(state.sheet)