Skip to content

Commit f94c5fc

Browse files
committed
docs(ten-moss): remove em-dashes; drop BENCHMARK.md + its reference
- README: replace em-dashes with commas/colons - delete BENCHMARK.md (memU-vs-Moss benchmark guide) and the paragraph that linked it; keep the self-contained moss_simulate_remote_ms latency tip
1 parent ca621eb commit f94c5fc

2 files changed

Lines changed: 25 additions & 118 deletions

File tree

apps/ten-moss/BENCHMARK.md

Lines changed: 0 additions & 86 deletions
This file was deleted.

apps/ten-moss/README.md

Lines changed: 25 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Voice Assistant with Moss (TEN Framework)
22

3-
A real-time voice agent built on the [TEN Framework](https://github.com/ten-framework/ten-framework) that grounds its answers in a [Moss](https://moss.dev) session. On every final ASR transcript the control extension asks Moss for session-scoped context (~1–10ms, in-process) and injects it into the LLM prompt before the model responds so answers reflect your knowledge base with no perceptible added latency.
3+
A real-time voice agent built on the [TEN Framework](https://github.com/ten-framework/ten-framework) that grounds its answers in a [Moss](https://moss.dev) session. On every final ASR transcript the control extension asks Moss for session-scoped context (~1–10ms, in-process) and injects it into the LLM prompt before the model responds, so answers reflect your knowledge base with no perceptible added latency.
44

55
The Moss integration lives in the `main_python` control extension and is powered by the [`ten-moss`](../../packages/ten-moss) package (`MossSessionManager`).
66

@@ -35,9 +35,9 @@ agora_rtc ──▶ caller hears the answer
3535

3636
The Moss delta over the stock TEN voice assistant is small and lives in three places in `main_python`:
3737

38-
- `config.py` `MainControlConfig` inherits `MossSessionConfig` (the `moss_*` properties).
39-
- `extension.py` `on_init` opens the Moss session (`MossSessionManager.from_config(...).open()`), best-effort.
40-
- `extension.py` `_on_asr_result` `query_context(text)` and prepends the grounding to the user's turn.
38+
- `config.py`: `MainControlConfig` inherits `MossSessionConfig` (the `moss_*` properties).
39+
- `extension.py` `on_init`: opens the Moss session (`MossSessionManager.from_config(...).open()`), best-effort.
40+
- `extension.py` `_on_asr_result`: `query_context(text)` and prepends the grounding to the user's turn.
4141

4242
## Provenance
4343

@@ -52,13 +52,13 @@ ASR handler.
5252

5353
## Prerequisites
5454

55-
- A **TEN Framework checkout**. This example references shared TEN extensions via relative paths (`../../../ten_packages/extension/...`) and runs with TEN's own tooling, so it lives **inside** a TEN Framework repo. It ships the TEN app (`tenapp/`) not the repo-level run harness (playground / server / Taskfile / Dockerfile), which the TEN Framework provides.
56-
- A **Moss** project (`MOSS_PROJECT_ID` / `MOSS_PROJECT_KEY`) [moss.dev](https://moss.dev).
55+
- A **TEN Framework checkout**. This example references shared TEN extensions via relative paths (`../../../ten_packages/extension/...`) and runs with TEN's own tooling, so it lives **inside** a TEN Framework repo. It ships the TEN app (`tenapp/`), not the repo-level run harness (playground / server / Taskfile / Dockerfile), which the TEN Framework provides.
56+
- A **Moss** project (`MOSS_PROJECT_ID` / `MOSS_PROJECT_KEY`), [moss.dev](https://moss.dev).
5757
- Provider keys: **Agora** (transport), **Deepgram** (STT), **OpenAI** (LLM), **ElevenLabs** (TTS).
5858

5959
## Run
6060

61-
1. **Build the demo knowledge index** (from this directory needs only the Moss SDK):
61+
1. **Build the demo knowledge index** (from this directory, needs only the Moss SDK):
6262
```bash
6363
cp .env.example .env # fill in MOSS_PROJECT_ID / MOSS_PROJECT_KEY / MOSS_INDEX_NAME
6464
python create_index.py # reads data/knowledge.jsonl, creates MOSS_INDEX_NAME
@@ -68,18 +68,18 @@ ASR handler.
6868
`ten-framework/ai_agents/agents/examples/voice-assistant-with-moss/tenapp/`, alongside
6969
the sibling `voice-assistant` example whose `Taskfile`/`playground`/`server` harness you
7070
reuse. `main_python` depends on [`ten-moss`](https://pypi.org/project/ten-moss/) (listed
71-
in `main_python/requirements.txt`), so `task install` installs it from PyPI automatically
71+
in `main_python/requirements.txt`), so `task install` installs it from PyPI automatically,
7272
no manual step needed.
7373

7474
3. **Run with TEN's tooling** from that example dir (`task install && task run`, per the TEN
7575
docs), providing the same env vars as step 1. Then open the TEN playground
76-
(http://localhost:3000) and ask something covered by `data/knowledge.jsonl` e.g.
77-
*"how long do refunds take?"* to hear grounded answers.
76+
(http://localhost:3000) and ask something covered by `data/knowledge.jsonl`: e.g.
77+
*"how long do refunds take?"*, to hear grounded answers.
7878

7979
## Answer quality with vs without Moss (`compare.py`, no voice stack)
8080

81-
`compare.py` answers the same questions with the same LLM twice once **without** Moss and
82-
once **with** the Moss grounding the agent injects so you can see the improvement without
81+
`compare.py` answers the same questions with the same LLM twice, once **without** Moss and
82+
once **with** the Moss grounding the agent injects, so you can see the improvement without
8383
standing up the full voice pipeline. It needs only your Moss + OpenAI keys (no Agora/STT/TTS):
8484

8585
```bash
@@ -101,7 +101,7 @@ Sample run (`gpt-4o-mini` over `data/knowledge.jsonl`):
101101

102102
Without grounding the model confidently invents plausible-but-wrong specifics; with Moss it
103103
answers from your knowledge base. This is the exact delta the live voice agent applies per
104-
turn flip `enable_moss` in `property.json` to A/B the same thing in the playground.
104+
turn, flip `enable_moss` in `property.json` to A/B the same thing in the playground.
105105

106106
## Per-turn latency and retrieval logs (live, in the agent)
107107

@@ -122,34 +122,27 @@ And in the playground transcript you see, per turn, **what Moss retrieved + the
122122
<the assistant's spoken answer>
123123
```
124124

125-
It also emits a **per-turn latency breakdown** a grep-able log line *and* a note in the
126-
transcript so you can see where the turn's time goes across the pipeline:
125+
It also emits a **per-turn latency breakdown**: a grep-able log line *and* a note in the
126+
transcript, so you can see where the turn's time goes across the pipeline:
127127

128128
```
129129
[latency-breakdown] turn=3 moss_retrieval_ms=2 llm_ttft_ms=480 llm_total_ms=1150 turn_total_ms=1160
130130
```
131131

132-
- **moss_retrieval_ms** the SDK's `SearchResult.time_taken_ms` (in-process retrieval engine time).
133-
- **llm_ttft_ms** time to the LLM's first token after dispatch.
134-
- **llm_total_ms** full LLM generation for the turn.
135-
- **turn_total_ms** ASR-final → LLM-final (the whole control-side turn).
132+
- **moss_retrieval_ms**: the SDK's `SearchResult.time_taken_ms` (in-process retrieval engine time).
133+
- **llm_ttft_ms**: time to the LLM's first token after dispatch.
134+
- **llm_total_ms**: full LLM generation for the turn.
135+
- **turn_total_ms**: ASR-final → LLM-final (the whole control-side turn).
136136

137137
ASR timing appears in the Deepgram STT extension logs and TTS audio-out in the ElevenLabs
138-
TTS logs (both per turn in the worker log) so between those and the line above you get the
138+
TTS logs (both per turn in the worker log), so between those and the line above you get the
139139
full component-by-component breakdown.
140140

141-
**TEN default retrieval vs Moss (real numbers).** TEN's shipped memory/RAG backends
142-
(memU, OceanBase PowerRAG, EverMemOS) are all remote services — every turn is a network
143-
round trip. To compare TEN's default (memU) against Moss with real logged latency from
144-
both agents, follow **[`BENCHMARK.md`](BENCHMARK.md)**: it adds the same one‑line
145-
latency log to TEN's shipped `voice-assistant-with-memU` example, then you run both agents
146-
and read `[retrieval-latency]` from each (memU: hundreds of ms; Moss: single‑digit ms).
141+
**Hear the latency Moss saves.** Set `moss_simulate_remote_ms` on the `main_control`
142+
node in `tenapp/property.json` to imitate a remote store's network round trip, then
143+
re-run `task run`:
147144

148-
**Quick single‑agent approximation (no memU key).** If you just want to hear the effect in
149-
this one agent, set `moss_simulate_remote_ms` on the `main_control` node in
150-
`tenapp/property.json` to a remote‑like latency and re‑run `task run`:
151-
152-
- `0` → Moss in‑process (~2 ms) — the agent replies immediately.
145+
- `0` → Moss in-process (~2 ms), the agent replies immediately.
153146
- `400` → the same agent, same answer, but audibly **pauses ~400 ms before every reply**.
154147

155148
## Configuration
@@ -163,6 +156,6 @@ assistant with no grounding; set `moss_simulate_remote_ms` to imitate a slow rem
163156
## Testing status
164157

165158
The `ten-moss` package is covered by offline unit tests (`packages/ten-moss/tests/`).
166-
This end-to-end app is **not** run in CI it requires the TEN toolchain plus paid
159+
This end-to-end app is **not** run in CI, it requires the TEN toolchain plus paid
167160
Agora/Deepgram/OpenAI/ElevenLabs credentials, so it is validated manually via the
168161
steps above.

0 commit comments

Comments
 (0)