Examples/voice agent live retrieval UI by samanyugoyal2010 · Pull Request #409 · usemoss/moss

samanyugoyal2010 · 2026-07-17T20:36:22Z

Summary

Enhances the existing moss-live-labs/examples/voice-agent with a live retrieval web UI and region metadata filtering, including review fixes from the prior iteration.

Closes #348

Live retrieval web UI (`web/`)

A Next.js app that renders the call next to a Moss · Knowledge Base panel, showing the documents retrieved for each turn with scores and per-query latency. Data is published on a moss.retrieval data channel.

Region metadata filtering

A US / EU picker in the UI publishes the region on a moss.region data channel. The agent scopes each query with a metadata filter so US and EU callers get the right policy from the same index, while region-agnostic FAQs (region: all) always match.

Type of Change

New feature (non-breaking change which adds functionality)
This change requires a documentation update

Try it

uv sync && cp .env.example .env
python seed_index.py
livekit-server --dev
python agent.py dev
cd web && npm install && cp .env.local.example .env.local && npm run dev

Docs: https://docs.moss.dev/docs/integrate/metadata-filtering

Enhances the customer-service voice-agent example with: - A Next.js web UI that shows live Moss retrieval side by side with the conversation, lighting up per turn with per-query latency. - Region metadata filtering: a US/EU picker in the UI publishes the region on a data channel; the agent scopes queries with a metadata filter (region in [selected, all]) so US and EU callers get the right policy (e.g. 30-day vs 14-day returns) from one index. - seed_index.py and data/faqs.json (20 FAQs tagged by category/region). - A demo script. The agent stays customer-facing and never mentions indexes or regions.

- README: list Cartesia as TTS (OpenAI=LLM, Deepgram=STT), add CARTESIA_API_KEY, fix DEMO_SCRIPT link to DEMO_SCRIPT_METADATA.md. - next.config: derive dir from import.meta.url (Node 18 compatible). - agent.py: validate region from data channel against an allow-list; fix stale 'upload.py' hint to 'seed_index.py'. - seed_index.py: fail fast if Moss credentials are missing. - RetrievalPanel: add type=button + aria-pressed on the region toggle.

… validates env + uses crypto.randomUUID (no hard-coded cred fallback)

- Require the index to load locally (fatal on failure): region metadata filtering is ignored on cloud fallback, so a silent warning would break the demo's point. - Skip empty/interim transcriptions before querying Moss. - Validate Moss creds in entrypoint; publish_data uses payload= keyword. - Add roomName to the token response type.

…p transcript history, Node 18.18+, note unauth token route is local-dev only

Address FAQ legal accuracy, region race conditions, accessibility, token hardening, and make npm run lint usable with ESLint config. Co-authored-by: Cursor <cursoragent@cursor.com>

cubic-dev-ai

All reported issues were addressed across 22 files

_{Tip: instead of fixing issues one by one fix them all with cubic
Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic}

Harden the local token route, align docs with uv run / Cloud setup, fix FAQ contradictions and UI region races, and migrate lint to ESLint flat config. Co-authored-by: Cursor <cursoragent@cursor.com>

samanyugoyal2010 · 2026-07-17T20:50:27Z

@cubic.dev

cubic-dev-ai · 2026-07-17T20:50:37Z

@cubic.dev

@samanyugoyal2010 I have started the AI code review. It will take a few minutes to complete.

samanyugoyal2010 · 2026-07-17T20:56:19Z

@claude how does this PR look to you

cubic-dev-ai

All reported issues were addressed across 22 files

_{Tip: instead of fixing issues one by one fix them all with cubic
Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic}

…ad limits Bind the Next server to loopback, stop trusting Host for auth, serialize region publishes, re-query on mid-flight region changes, truncate retrieval packets, restore the base voice pipeline, and fix remaining FAQ/CSS compatibility issues. Co-authored-by: Cursor <cursoragent@cursor.com>

cubic-dev-ai

All reported issues were addressed across 9 files (changes from recent commits).

_{Tip: instead of fixing issues one by one fix them all with cubic
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

Require verified loopback binding for null peer IPs, take XFF from the trusted rightmost hop, make retrieval region mandatory, commit successful publishes before UI suppression, and revalidate region after every await. Co-authored-by: Cursor <cursoragent@cursor.com>

cubic-dev-ai

All reported issues were addressed across 8 files (changes from recent commits).

_{Tip: instead of fixing issues one by one fix them all with cubic
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

…ader, region deferral Use cross-env for portable scripts, allow loopback-bound production starts, make TRUST_PROXY_HEADER an exclusive strategy, and defer region changes until the current reply finishes so spoken policy matches retrieval. Co-authored-by: Cursor <cursoragent@cursor.com>

cubic-dev-ai

All reported issues were addressed across 5 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic}

…code Extract a pure tokenGuard module with focused node:test coverage, simplify turn retrieval to a single query/publish under deferral, and remove unused session_holder. Co-authored-by: Cursor <cursoragent@cursor.com>

cubic-dev-ai

All reported issues were addressed across 6 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic}

…st abuse Validate 127/8 octets, require TRUSTED_PROXIES before honoring forwarded IPs, restore TRUST_PROXY_HEADER misconfig warnings, and allowlist Host on the loopback listen path to block DNS rebinding. Co-authored-by: Cursor <cursoragent@cursor.com>

cubic-dev-ai

All reported issues were addressed across 4 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic}

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

Move empty TRUSTED_PROXIES and invalid TRUST_PROXY_HEADER warnings out of per-request peerIp so token traffic cannot flood the logs. Co-authored-by: Cursor <cursoragent@cursor.com>

cubic-dev-ai

All reported issues were addressed across 1 file (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic}

HarshaNalluru and others added 6 commits July 6, 2026 20:12

examples(voice-agent): set tsconfig baseUrl for @/ paths; token route…

3f9a979

… validates env + uses crypto.randomUUID (no hard-coded cred fallback)

examples(voice-agent): neutral context label + no-match guardrail, ca…

23dc412

…p transcript history, Node 18.18+, note unauth token route is local-dev only

examples(voice-agent): fix review issues for live retrieval UI

784931b

Address FAQ legal accuracy, region race conditions, accessibility, token hardening, and make npm run lint usable with ESLint config. Co-authored-by: Cursor <cursoragent@cursor.com>

samanyugoyal2010 requested review from HarshaNalluru and r4ghu as code owners July 17, 2026 20:36