Drop essay comments from the Moss sample files.

Keep only the notes a stranger cannot infer: SSE must end with
data: [DONE], Bearer is required off mock, FastAPI mounts skip
lifespan, and retrieval notes need their own stream_id.

Author: abojja9

apps/agora-custom-llm-moss/server/src/llm.py

@@ -1,18 +1,9 @@
-"""
-Custom LLM endpoint with Moss grounding.
+"""OpenAI-compatible /chat/completions with Moss.
 
 Forked from Agora's custom-llm recipe (MIT):
 https://github.com/AgoraIO-Conversational-AI/recipe-agent-custom-llm/blob/main/server/src/llm.py
 
-Agora cloud POSTs here. Two modes, same index:
-
-  ambient  last user text -> query_context -> prepend -> upstream LLM
-  tool     advertise search_knowledge_base to the upstream LLM;
-           run Moss here if the model calls it (cap 2);
-           stream only the final spoken answer.
-
-SSE contract: each line is `data: {json}`, end with `data: [DONE]`.
-Non-mock requests need `Authorization: Bearer`.
+SSE must end with `data: [DONE]`. Non-mock requests need Authorization: Bearer.
 """
 
 from __future__ import annotations
@@ -125,7 +116,6 @@ def as_dict(msg: Any) -> dict[str, Any]:
 
 
 async def query_moss(session, user_text: str) -> str:
-    """Fail-open: empty string if Moss is missing or errors."""
     if session is None:
         return ""
     try:
@@ -261,7 +251,7 @@ async def tool_answer(messages: list, session, mock: bool) -> str:
 
 
 async def call_upstream(messages: list, tools: list | None = None, raw: bool = False):
-    """Non-streaming upstream call. We only stream the final spoken answer to Agora."""
+    # Upstream is non-streaming; only the final answer is sent to Agora as SSE.
     import httpx
 
     payload = [as_dict(m) for m in messages]
@@ -295,8 +285,7 @@ def create_app(moss_mode: str = "ambient") -> FastAPI:
     state: dict[str, Any] = {"session": None, "ready": False}
 
     async def get_session():
-        # Open on first use so this works both standalone and mounted
-        # under server.py (FastAPI does not always run a mount's lifespan).
+        # FastAPI does not always run a mounted app's lifespan.
         if not state["ready"]:
             state["session"] = await open_moss()
             state["ready"] = True

apps/ten-moss/README.md

@@ -37,8 +37,6 @@ flowchart LR
     class ctl,idx moss
 ```
 
-Everything on the retrieval path runs inside the agent process. There is no network hop between the transcript arriving and the grounded prompt reaching the LLM.
-
 ## What's in this directory
 
 This example ships the TEN app plus a small index builder; the run harness (playground, server, Taskfile, Dockerfile) comes from the TEN Framework, so `tenapp/` drops into any TEN checkout.
@@ -97,30 +95,9 @@ The Moss delta lives in `main_python`:
 | `extension.py` `on_cmd` | Tool: `query_context(arguments.query)` and return `{type: "llmresult", content: grounding}`. |
 | `tenapp/property.json` | `voice_assistant` (ambient, auto-start) and `voice_assistant_tools`. |
 
-Anatomy of a turn:
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant User
-    participant STT as Deepgram STT
-    participant Ctl as main_control
-    participant Moss as Moss session (in-process)
-    participant LLM as OpenAI LLM
-    participant TTS as ElevenLabs TTS
-
-    User->>STT: speech (via agora_rtc + streamid_adapter)
-    STT->>Ctl: asr_result (final)
-    Ctl->>Moss: query_context(text)
-    Moss-->>Ctl: grounding (single-digit ms)
-    Ctl->>LLM: context + [Current User Question] + text
-    LLM-->>TTS: streamed response
-    TTS-->>User: audio (via agora_rtc)
-```
-
 ## Measure the latency
 
-Every turn, the control extension logs the retrieval cost using the SDK's own `SearchResult.time_taken_ms` (surfaced by `ten-moss` as `last_time_taken_ms`), with the wall clock alongside for reference:
+Logs use the SDK `SearchResult.time_taken_ms` (`ten-moss.last_time_taken_ms`), plus wall clock:
 
 ```
 [retrieval-latency] backend=moss(in-process) time_taken_ms=2 (wall_clock=64ms)
@@ -134,7 +111,7 @@ In the playground transcript you see, per turn, what Moss retrieved plus the SDK
 <the assistant's spoken answer>
 ```
 
-The extension also emits a per-turn latency breakdown, both as a grep-able log line and as a note in the transcript, so you can see where each turn's time goes:
+Per-turn breakdown:
 
 ```
 [latency-breakdown] turn=3 moss_retrieval_ms=2 llm_ttft_ms=480 llm_total_ms=1150 turn_total_ms=1160
@@ -147,11 +124,7 @@ The extension also emits a per-turn latency breakdown, both as a grep-able log l
 | `llm_total_ms` | Full LLM generation for the turn. |
 | `turn_total_ms` | ASR-final to LLM-final (the whole control-side turn). |
 
-ASR timing appears in the Deepgram STT extension logs and TTS audio-out in the ElevenLabs TTS logs (both per turn in the worker log), so between those and the lines above you get the full component-by-component breakdown.
-
-### Benchmark against TEN's default retrieval
-
-TEN's shipped memory/RAG backends (memU, OceanBase PowerRAG, EverMemOS) are remote services that pay a network round trip every turn, whereas Moss retrieves in-process, so the same grounding is a local call of single-digit milliseconds.
+ASR timing is in the Deepgram logs; TTS audio-out is in the ElevenLabs logs.
 
 ## Configuration
 
@@ -178,7 +151,7 @@ No Agora, no Deepgram, no mic. Gold phrases are the 10 FAQs.
 python bench/run.py --echo-grounding
 ```
 
-`--echo-grounding` needs no LLM key. With `MOSS_*` set it reports `moss_retrieval_ms`. Without them it still prints the table from the local FAQ file. The tool arm always searches in that smoke (no LLM to decide). See `bench/README.md`.
+See `bench/README.md`.
 
 ## Provenance
 

apps/ten-moss/bench/run.py

@@ -1,13 +1,7 @@
-"""Offline gold-phrase bench: ambient vs tool vs no-Moss.
+"""Gold-phrase bench. python bench/run.py --echo-grounding
 
-    python bench/run.py --echo-grounding
-
-No mic, no Agora, no Deepgram, no LLM key.
-With MOSS_* set, ambient and tool call MossSessionManager.query_context.
-Without them, those arms look up the matching FAQ in data/knowledge.jsonl
-so the table still prints (moss_retrieval_ms is then n/a).
-
---echo-grounding has no chat model, so the tool arm always searches.
+No LLM key. Tool arm always searches (no model). Without MOSS_* the
+FAQ file is used and moss_retrieval_ms is n/a.
 """
 
 from __future__ import annotations
@@ -44,7 +38,6 @@ def contains_gold(text: str, gold: list[str]) -> bool:
 
 
 def lookup_faq(query: str, queries: list[dict], docs: list[dict]) -> str:
-    """Return the FAQ that belongs to this published query. No Moss needed."""
     by_id = {str(doc.get("id")): doc for doc in docs}
     for row in queries:
         if row.get("query") == query:
@@ -55,7 +48,6 @@ def lookup_faq(query: str, queries: list[dict], docs: list[dict]) -> str:
 
 
 async def query_moss(session, query: str) -> tuple[str, float | None, float | None]:
-    """Fail-open: empty context on error. Returns (text, sdk_ms, wall_ms)."""
     t0 = time.perf_counter()
     try:
         context = await session.query_context(query)

apps/ten-moss/tenapp/ten_packages/extension/main_python/config.py

@@ -4,7 +4,5 @@
 
 
 class MainControlConfig(MossSessionConfig):
-    """Moss session fields (moss_*) plus greeting and moss_mode."""
-
     greeting: str = "Hello, I am your AI assistant."
     moss_mode: Literal["ambient", "tool"] = "ambient"

apps/ten-moss/tenapp/ten_packages/extension/main_python/extension.py

@@ -33,10 +33,6 @@
 
 
 class MainControlExtension(AsyncExtension):
-    """
-    The entry point of the agent module.
-    Consumes semantic AgentEvents from the Agent class and drives the runtime behavior.
-    """
 
     def __init__(self, name: str):
         super().__init__(name)
@@ -51,9 +47,6 @@ def __init__(self, name: str):
         self.turn_id: int = 0
         self.session_id: str = "0"
 
-        # Per-turn latency breakdown (see _log_latency_breakdown). main_control
-        # orchestrates retrieval -> LLM -> TTS, so it can time those stages; ASR
-        # timing lives in the STT extension logs and TTS audio-out in the TTS logs.
         self._turn_t0: float | None = None
         self._retrieval_ms: float | None = None
         self._llm_sent_at: float | None = None
@@ -67,12 +60,9 @@ def _current_metadata(self) -> dict:
     async def on_init(self, ten_env: AsyncTenEnv):
         self.ten_env = ten_env
 
-        # Load config from runtime properties
         config_json, _ = await ten_env.get_property_to_json(None)
         self.config = MainControlConfig.model_validate_json(config_json)
 
-        # Open a Moss session for ambient, session-scoped grounding (best-effort:
-        # if the session can't open, the agent still runs, just without grounding).
         self.moss = None
         if self.config.enable_moss and self.config.moss_index_name:
             try:
@@ -87,7 +77,6 @@ async def on_init(self, ten_env: AsyncTenEnv):
 
         self.agent = Agent(ten_env)
 
-        # Now auto-register decorated methods
         for attr_name in dir(self):
             fn = getattr(self, attr_name)
             event_type = getattr(fn, "_agent_event_type", None)
@@ -97,7 +86,6 @@ async def on_init(self, ten_env: AsyncTenEnv):
         if self.config.moss_mode == "tool":
             await self._register_search_knowledge_base()
 
-    # === Register handlers with decorators ===
     @agent_event_handler(UserJoinedEvent)
     async def _on_user_joined(self, event: UserJoinedEvent):
         self._rtc_user_count += 1
@@ -118,8 +106,6 @@ async def _on_tool_register(self, event: ToolRegisterEvent):
     @agent_event_handler(ASRResultEvent)
     async def _on_asr_result(self, event: ASRResultEvent):
         self.session_id = event.metadata.get("session_id", "100")
-        # session_id is a string in the event schema; parse defensively so a
-        # non-numeric value can't crash the ASR handler and break the voice loop.
         try:
             stream_id = int(self.session_id)
         except (TypeError, ValueError):
@@ -130,13 +116,11 @@ async def _on_asr_result(self, event: ASRResultEvent):
             await self._interrupt()
         if event.final:
             self.turn_id += 1
-            self._turn_t0 = time.perf_counter()  # turn clock starts at ASR-final
+            self._turn_t0 = time.perf_counter()
             self._retrieval_ms = None
             self._last_grounding = ""
             self._last_sdk_ms = None
             llm_input = event.text
-            # Ambient searches here and prepends. Tool mode sends the raw
-            # transcript; the LLM calls search_knowledge_base if it needs facts.
             if self.moss is not None and self.config.moss_mode != "tool":
                 context = await self._query_moss(event.text)
                 if context:
@@ -150,7 +134,6 @@ async def _on_asr_result(self, event: ASRResultEvent):
 
     @agent_event_handler(LLMResponseEvent)
     async def _on_llm_response(self, event: LLMResponseEvent):
-        # First streamed token of this turn -> time-to-first-token.
         if (
             event.type == "message"
             and self._llm_first_at is None
@@ -196,7 +179,6 @@ async def on_cmd(self, ten_env: AsyncTenEnv, cmd: Cmd):
     async def on_data(self, ten_env: AsyncTenEnv, data: Data):
         await self.agent.on_data(data)
 
-    # === helpers ===
     async def _register_search_knowledge_base(self) -> None:
         tool = LLMToolMetadata(
             name=SEARCH_KNOWLEDGE_BASE,
@@ -219,7 +201,6 @@ async def _register_search_knowledge_base(self) -> None:
         )
 
     async def _on_tool_call(self, cmd: Cmd) -> None:
-        """search_knowledge_base: query_context, return empty on error."""
         try:
             raw, _ = cmd.get_property_to_json(None)
             payload = json.loads(raw) if raw else {}
@@ -256,7 +237,6 @@ async def _on_tool_call(self, cmd: Cmd) -> None:
         await self.ten_env.return_result(result)
 
     async def _query_moss(self, user_text: str) -> str:
-        """query_context + latency log. Never raise into the voice loop."""
         if self.moss is None:
             return ""
         try:
@@ -279,13 +259,6 @@ async def _query_moss(self, user_text: str) -> str:
             return ""
 
     async def _log_latency_breakdown(self):
-        """Per-turn latency breakdown for onboarding/debugging.
-
-        Emits a grep-able log line ('[latency-breakdown]') and a reasoning note
-        in the transcript so users can see where each turn's time goes:
-        Moss retrieval, LLM time-to-first-token, and full LLM generation. (ASR
-        timing is in the STT extension logs; TTS audio-out in the TTS logs.)
-        """
         now = time.perf_counter()
 
         def _ms(v: float | None) -> str:
@@ -309,23 +282,18 @@ def _ms(v: float | None) -> str:
             f"⏱ turn {self.turn_id} · Moss {_ms(retrieval)} ms (time_taken_ms) · "
             f"LLM first token {_ms(ttft)} ms · LLM total {_ms(llm_total)} ms"
         )
-        # Own stream id (distinct from the answer's 100 and the retrieval note's).
         await self._send_transcript(
             "assistant", note, True, 710_000_000 + self.turn_id, data_type="reasoning"
         )
 
     async def _send_retrieval_note(self, grounding: str, time_taken_ms):
-        """Show what Moss retrieved this turn + the SDK's time_taken_ms, so users
-        see the retrieval *results* alongside the timing (the LLM answer follows
-        as its own transcript message)."""
         ms_txt = f"{time_taken_ms}" if time_taken_ms is not None else "n/a"
         body = (
             f"🔎 Moss · retrieved in {ms_txt} ms (SDK time_taken_ms)\n\n{grounding}"
             if grounding
             else f"🔎 Moss · retrieved in {ms_txt} ms (SDK time_taken_ms) — no match"
         )
-        # Own stream id so this note is a separate transcript item, not merged
-        # into (and replacing) the assistant answer bubble at stream_id 100.
+        # Distinct stream_id so this note is not merged into the answer bubble.
         await self._send_transcript(
             "assistant", body, True, 700_000_000 + self.turn_id, data_type="reasoning"
         )
@@ -338,9 +306,6 @@ async def _send_transcript(
         stream_id: int,
         data_type: Literal["text", "reasoning"] = "text",
     ):
-        """
-        Sends the transcript (ASR or LLM output) to the message collector.
-        """
         if data_type == "text":
             await _send_data(
                 self.ten_env,
@@ -381,9 +346,6 @@ async def _send_transcript(
         )
 
     async def _send_to_tts(self, text: str, is_final: bool):
-        """
-        Sends a sentence to the TTS system.
-        """
         request_id = f"tts-request-{self.turn_id}"
         await _send_data(
             self.ten_env,
@@ -401,9 +363,6 @@ async def _send_to_tts(self, text: str, is_final: bool):
         )
 
     async def _interrupt(self):
-        """
-        Interrupts ongoing LLM and TTS generation. Typically called when user speech is detected.
-        """
         self.sentence_fragment = ""
         await self.agent.flush_llm()
         await _send_data(