Vexium Voice

A bilingual Spanish/English receptionist reference application built with FastAPI, Qwen and Next.js. It demonstrates tool-driven appointment booking, caller memory, reminders and a dashboard for conversation events.

Status: reference/demo application under active development. The July 2026 hackathon demo is historical; no hosted demo availability is promised. See operating boundaries before deploying.

Guía en español · Contributing · Architecture · Changelog

The same business functions serve two conversational paths:

• Text: browser → FastAPI → Qwen tool loop → business functions.
• Voice: browser audio → FastAPI WebSocket → Deepgram Voice Agent with Qwen → business functions.
• Dashboard: stored events → FastAPI JSON/SSE endpoints → Next.js dashboard.
• Quality scoring: completed voice calls and text bookings can be evaluated by a separate Qwen judge. Its scores are model assessments, not human-verified accuracy.

Dental and restaurant examples include simulated availability, reservations, calendar integration, checkout links, SMS reminders and per-tenant event storage. All prices, business profiles and example caller data are demonstration data.

Use Python 3.12 or 3.13, uv 0.11.17+, and Node 24. From PowerShell, bash or another terminal:

git clone https://github.com/Str0k/vexium-voice-qwen.git
cd vexium-voice-qwen
uv sync --locked
uv run uvicorn server:app --host 127.0.0.1 --port 8000

In a second terminal, from the repository root:

cd web
npm ci
npm run dev

Open localhost:3000, the dashboard, or the HTTP API documentation. The backend is local-only with these commands.

Without provider configuration, the UI, API health endpoint and mocked test suite work. Live text generation needs a Qwen account and configuration; live voice also needs Deepgram. Copy the tracked environment example to a local environment file only when setting up providers. The configuration reference is in .env.example. Provider usage may incur charges.

Configuration enables the corresponding live integration. Missing configuration uses the behavior below; the dashboard reflects configuration rather than probing provider health.

The original Alibaba deployment notes and hackathon submission are historical reference material.

The Python suite mocks external services. Outbound connections are restricted to local loopback so tests cannot call cloud services accidentally.

uv run ruff check .
uv run ruff format --check .
uv run pytest --cov --cov-report=term-missing --cov-fail-under=65

From web, verify the frontend:

npm run lint -- --max-warnings=0
npm audit --omit=dev --audit-level=high
npm run build

CI runs Python checks on Linux (3.12/3.13) and Windows (3.12), plus frontend checks on Node 24. The coverage floor prevents regressions; it does not imply that live calls, provider APIs or production behavior have been fully tested.

Start with a reproducible issue or a focused improvement. Installation failures, voice lifecycle tests, explicit timezone handling and accessibility improvements are useful contributions. See CONTRIBUTING.md for setup and review expectations.

Released under the MIT license.