NEXA 247

Nexa 247 is a multi-tenant voice AI orchestration platform that dynamically provisions and manages AI receptionists for trade businesses. Each inbound call triggers a real-time pipeline: telephony ingestion, tenant resolution, dynamic prompt assembly, tool-augmented conversation, and post-call intelligence extraction — all at sub-second latency.

This is not a chatbot with a phone number. This is a stateful, tool-calling voice agent that books appointments, qualifies leads, and escalates emergencies — in real-time, mid-conversation.

# Hot path: phone_number_id → full assistant config
async def handle_assistant_request(payload):
    phone_id = payload["phone_number_id"]

    # 1. Tenant resolution — Redis-cached, <0.5ms hit rate >99%
    tenant = await cache.get_tenant_by_phone(phone_id)

    # 2. Dynamic prompt assembly — skills-based + KB block
    system_prompt = build_prompt(
        base_skills=["greeting", "booking", "lead_qualification"],
        tenant_config=tenant.ai_config,
        services=tenant.services,
        business_hours=tenant.hours,
        personality=tenant.voice_personality,
        smb_knowledge=tenant.smb_knowledge,  # KB mode routing
    )

    # 3. Tool injection — only tools this tenant has enabled
    tools = resolve_tools(tenant)  # calendar, sms, lead_capture, kb_retrieval

    # 4. Return complete assistant config
    return AssistantConfig(
        model="claude-sonnet-4-20250514",
        voice={"provider": "11labs", "voice_id": "australian_male"},
        system_prompt=system_prompt,
        tools=tools,
        metadata={"tenant_id": tenant.id}
    )

Key design decisions

• No DB hit on the hot path — tenant config cached in Redis with TTL invalidation
• Skills-based prompt composition — markdown skill files loaded at boot, composed per-tenant
• KB mode routing — markdown KB embedded inline; vector KB injects advisory + retrieval tool
• Tool injection — tenants only get tools they've configured
• Stateless webhook handler — any backend instance can serve any call

Isolation guarantees

// answer_product_service_question — RAG retrieval mid-call
{
  "trigger": "Caller asks about pricing, services, or specific products",
  "flow": [
    "1. LLM detects information question (not a booking action)",
    "2. VAPI sends function-call webhook to Nexa backend",
    "3. Backend runs hybrid_search(tenant_id, question, top_k=5)",
    "   ├─ BM25 leg: PostgreSQL tsvector FTS (GIN index)",
    "   ├─ Vector leg: pgvector cosine ANN (HNSW index)",
    "   └─ Fuse both legs with Reciprocal Rank Fusion (k=60)",
    "4. Return top-5 chunk contents to VAPI",
    "5. LLM synthesises answer from retrieved context",
    "6. AI responds to caller with accurate, grounded information"
  ],
  "latency": "~50–120ms (both legs run concurrently via asyncio.gather)",
  "fallback": "If KB empty or inactive, AI answers from form-only profile"
}

backend/skills/
├── greeting.md           # G'day opener, business intro
├── booking.md            # Calendar availability + booking flow
├── lead_qualification.md # Urgency scoring, service matching
├── emergency_handling.md # Escalation protocols
├── closing.md            # Call wrap-up, confirmation
└── personality/
    ├── tradie_casual.md  # Warm, Australian, mate-oriented
    ├── professional.md   # Formal business tone
    └── custom/           # Per-tenant personality overrides

def build_system_prompt(tenant: Tenant, smb_knowledge: dict) -> str:
    sections = []

    # Core identity
    sections.append(f"You are the AI receptionist for {tenant.business_name}.")

    # Load skill modules
    for skill in tenant.enabled_skills:
        sections.append(load_skill(skill))  # Cached markdown

    # Inject business context
    sections.append(format_services(tenant.services))
    sections.append(format_hours(tenant.business_hours))

    # ── KB block — mode-routed ────────────────────────────────
    kb_block = _build_knowledge_base_block(smb_knowledge, tenant.vertical)
    if kb_block:
        sections.append(kb_block)
    # markdown mode → full text embedded in <knowledge_base> tags
    # vector mode   → advisory + "call answer_product_service_question"
    # form_only     → no block; AI answers from services list only

    # Personality layer
    sections.append(load_personality(tenant.voice_personality))

    return "\n\n".join(sections)

KB block modes

Ingest Pipeline

Hybrid Search at Query Time

Why hybrid over pure vector?

Infrastructure & concurrency controls

Eval infrastructure

• Langfuse integration — trace-level evaluation including KB tool call outcomes
• Automated test scenarios — synthetic callers with scripted personas
• Regression suite — every prompt change triggers eval re-run
• Per-tenant quality scores — identify underperforming configurations

Backend (Python Async)

Frontend (React SPA)

External Services

Infrastructure

Data Protection

• OAuth credential encryption: Fernet symmetric encryption for all stored tokens
• Webhook verification: HMAC-SHA256 signature validation on all inbound webhooks (VAPI, Stripe)
• Row-level security: PostgreSQL RLS ensures tenant data isolation (including smb_knowledge_chunks)
• JWT authentication: Supabase-issued JWTs with session refresh
• No PII in logs: Call transcripts stored in database only, not in application logs
• SSRF protection: Two-layer SSRF guard on all KB URL ingests (string-pattern + DNS resolution)
• Prompt injection sanitization: All scraped/uploaded KB content sanitized before storage

Australian Compliance

• GST handling: Built-in Australian GST calculation for all invoices
• ABN support: Tenant ABN storage for tax invoice generation
• Data residency: Supabase region selection for Australian data sovereignty
• Privacy Act alignment: Call recording consent handling in AI greeting

API Security

• Rate limiting: Redis-backed rate limiting on all public endpoints (including KB ingest)
• CORS configuration: Strict origin allowlisting (app.nexa247.ai only)
• Input validation: Pydantic models on every endpoint — no raw dict access
• Dependency scanning: Automated vulnerability checks in CI

Current architecture supports

• Concurrent calls: Limited only by VAPI account tier (not our backend)
• Webhook throughput: Async FastAPI handles 10K+ req/s per instance
• Tenant count: Horizontal scaling — add backend instances, no shared state
• KB retrieval: pgvector HNSW — sub-linear query time, scales to millions of chunks
• Database: Supabase managed PG with connection pooling (PgBouncer)

Scaling bottlenecks & mitigations

Cost at scale (per 1,000 tenants)

Near-Term (Q2–Q3 2026)

• Outbound calling engine: Appointment reminders, follow-up calls, no-show re-engagement
• Real-time WebSocket dashboard: Live call monitoring with transcript streaming
• Multi-calendar support: Outlook, Calendly, ServiceM8 integration
• Conversation memory: Cross-call context (repeat callers recognised)
• KB re-scrape scheduling: Auto-refresh KB on configurable interval (weekly/monthly)

Medium-Term (Q4 2026–Q1 2027)

• Fine-tuned voice model: Custom Australian voice model trained on trade conversations
• Predictive scheduling: ML-based optimal time slot recommendations
• Quote generation: AI extracts job scope from call → generates preliminary quote
• Multi-language support: Mandarin, Vietnamese, Arabic for diverse Australian communities
• KB analytics: Which questions hit the KB? Which miss? Drive content gap suggestions to tenants

Long-Term Vision

• Agentic workflow orchestration: Voice AI as the entry point to a full trade business automation platform
• Edge inference: On-device STT for <100ms first-word latency
• Federated learning: Cross-tenant conversation quality improvements without sharing data