FinVox

🚀 FinVox — Full System Setup & Deployment Guide

FinVox is an enterprise-grade Conversational Voice & Chat Multi-Agent Financial Advisory Platform engineered for Small and Medium Enterprises (SMEs).
This guide walks through cloning, configuring, database provisioning, and launching the full stack from scratch.

---

📑 Table of Contents

1. Architecture & Tech Stack
2. Prerequisites
3. External Cloud Services & API Keys
4. Step-by-Step Installation
   • Step 1: Clone the Repository
   • Step 2: Python Virtual Environment Setup
   • Step 3: Environment Variables Configuration
   • Step 4: Database & Schema Provisioning
   • Step 5: React Frontend Setup
5. Running the Application
6. Data Ingestion & Verification
7. Running Tests
8. Troubleshooting & Common Gotchas

---

🏛️ Architecture & Tech Stack

graph TD
    User["🧑‍💼 User (Browser / Mobile)"]
    
    subgraph Frontend["💻 Frontend (Port 5173)"]
        ReactUI["React 19 + TypeScript + Vite"]
        Recharts["Recharts Visualizations"]
        LiveKitClient["LiveKit WebRTC Audio Client"]
    end

    subgraph Backend["⚙️ Backend (Port 8000)"]
        FastAPI["FastAPI (Async REST & SSE Stream)"]
        LangGraph["LangGraph Multi-Agent Orchestrator"]
        Router["Intent Router & Guardrail"]
        VoiceAdapter["LiveKit Voice LLM Adapter"]
    end

    subgraph ExternalServices["☁️ Data & AI Infrastructure"]
        Supabase["Supabase (PostgreSQL + pgvector)"]
        Qdrant["Qdrant Cloud (Document Vector DB)"]
        OpenAI["OpenAI / Groq (LLM Inference)"]
        LiveKitCloud["LiveKit Cloud (WebRTC Voice SFU)"]
        Deepgram["Deepgram (Nova-3 Speech-to-Text)"]
        ElevenLabs["ElevenLabs (Turbo v2.5 Text-to-Speech)"]
        Tavily["Tavily (Live IRD / Market Search)"]
    end

    User <-->|HTTP / SSE / WebRTC| Frontend
    Frontend <-->|REST / SSE| FastAPI
    Frontend <-->|LiveKit Audio Stream| LiveKitCloud
    FastAPI <--> LangGraph
    LiveKitCloud <--> VoiceAdapter
    VoiceAdapter <--> LangGraph
    LangGraph <--> ExternalServices

• Backend: Python 3.11+, FastAPI, LangGraph, LangChain, SQLAlchemy.
• Voice Pipeline: LiveKit Agents SDK, Deepgram (Nova-3 STT), ElevenLabs (Turbo v2.5 TTS), Silero VAD.
• Frontend: React 19, TypeScript, Vite, Recharts, Lucide Icons, KaTeX math formatting.
• Databases: Supabase (PostgreSQL 15+ with pgvector), Qdrant Cloud (Vector store & CAG cache).

---

📋 Prerequisites

Ensure you have the following installed on your machine:

| Requirement | Minimum Version | Verification Command | | :--- | :--- | :--- | | Python | 3.11 or higher | python --version | | Node.js | 18.0 or higher | node -v | | npm | 9.0 or higher | npm -v | | Git | 2.30 or higher | git --version |

---

☁️ External Cloud Services & API Keys

Before starting, register and collect API keys for the following services:

1. Supabase (supabase.com):
   • Create a free project.
   • Obtain: Database Connection String (Session Pooler URI), Project URL, and Service Role Key.
2. Qdrant Cloud (cloud.qdrant.io):
   • Create a free cluster.
   • Obtain: QDRANT_URL and QDRANT_API_KEY.
3. OpenAI (platform.openai.com):
   • Obtain OPENAI_API_KEY (used for synthesis and GPT-4o-mini routing).
4. Groq (console.groq.com):
   • Obtain GROQ_API_KEY (used for ultra-fast structured extraction).
5. LiveKit Cloud (cloud.livekit.io):
   • Create a project.
   • Obtain: LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET.
6. Deepgram (deepgram.com):
   • Obtain DEEPGRAM_API_KEY (for speech-to-text).
7. ElevenLabs (elevenlabs.io):
   • Obtain ELEVEN_API_KEY (for text-to-speech audio synthesis).
8. Tavily Search (tavily.com):
   • Obtain TAVILY_API_KEY (for live IRD tax portal queries).

---

🛠️ Step-by-Step Installation

Step 1: Clone the Repository

git clone https://github.com/dinod001/FinVox.git
cd FinVox

---

Step 2: Python Virtual Environment Setup

On Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt

On macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

---

Step 3: Environment Variables Configuration

Create a .env file in the root project directory by copying the template below:

# ============================================================================
# Qdrant Cloud (Vector Knowledge Base for Documents & Semantic Cache)
# ============================================================================
QDRANT_URL=https://xxxxxxxx.us-west-1-0.aws.cloud.qdrant.io
QDRANT_API_KEY=your_qdrant_api_key
QDRANT_COLLECTION_NAME=finvox

# ============================================================================
# Supabase (CRM, User Sessions, Short-Term & Long-Term pgvector Memory)
# ============================================================================
# Use Transaction or Session Pooler URI on port 5432 or 6543
SUPABASE_DB_URL=postgresql://postgres.yourproject:[email protected]:5432/postgres
SUPABASE_URL=https://yourproject.supabase.co
SUPABASE_SERVICE_KEY=your_supabase_service_role_key

# ============================================================================
# LLM Providers
# ============================================================================
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxx
OPENROUTER_API_KEY=your_openrouter_key_optional

# ============================================================================
# Real-Time Voice Pipeline (LiveKit + STT + TTS)
# ============================================================================
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
DEEPGRAM_API_KEY=your_deepgram_api_key
ELEVEN_API_KEY=your_elevenlabs_api_key

# ============================================================================
# Search & Web Intelligence
# ============================================================================
TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxxxxxx

# ============================================================================
# Observability (Langfuse - Optional)
# ============================================================================
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
LANGFUSE_BASE_URL=https://us.cloud.langfuse.com

---

Step 4: Database & Schema Provisioning

FinVox requires database schemas for users, sessions, table registries, and pgvector embeddings. Initialize the database by running:

python scripts/setup/init_test_db.py

This script connects to Supabase, enables the vector extension, and builds:

• users — User credentials and profiles.
• chat_sessions — Active and archived chat sessions with auto-titling.
• st_messages — Short-term sliding-window conversation turns.
• mem_vectors — Long-term semantic user facts with HNSW cosine similarity index.
• table_registry — Metadata catalog for user-uploaded CSV/Excel financial ledgers.

---

Step 5: React Frontend Setup

Open a new terminal window, navigate to the frontend directory, and install dependencies:

cd ui/finvox
npm install

---

🏃 Running the Application

To run the full FinVox platform, start the three services in separate terminal tabs:

Terminal 1: FastAPI REST Backend

From the project root:

# Windows
.\.venv\Scripts\activate
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000

# macOS / Linux
source .venv/bin/activate
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000

• API Documentation (Swagger UI): http://localhost:8000/docs
• Health Check: http://localhost:8000/health

---

Terminal 2: Real-Time LiveKit Voice Worker

From the project root:

# Windows
.\.venv\Scripts\activate
python -m src.voice.run dev

# macOS / Linux
source .venv/bin/activate
python -m src.voice.run dev

When this connects successfully, you will see:
✓ Voice worker registered and waiting for LiveKit room participants.

---

Terminal 3: Vite React Web Client

From the ui/finvox directory:

cd ui/finvox
npm run dev

Open your browser and navigate to:
👉 http://localhost:5173

---

📥 Data Ingestion & Verification

FinVox supports dynamic dataset ingestion for both structured ledgers (CSVs) and unstructured documents (PDFs).

1. Ingest Sample Financial Ledger (CSV)

Upload via the Ingestion UI at http://localhost:5173/ingest or run the CLI ingestion script:

python scripts/ingest_file.py --file data/sample/apex_technologies_cashflow_ledger_2026.csv --user test_user_finvox

2. Ingest Sample Invoice (PDF)

Upload data/sample/sample_invoice.pdf via the UI or CLI:

python scripts/ingest_file.py --file data/sample/sample_invoice.pdf --user test_user_finvox

---

🧪 Running Tests

To verify the installation and agent workflows, run the test suites:

# Run all unit and integration tests
pytest tests/ -v

# Run orchestrator and multi-agent tests
pytest tests/test_orchestrator.py -v

# Run chunking and vector ingestion tests
pytest tests/test_ingest.py -v

---

🔍 Troubleshooting & Common Gotchas

1. Supabase Connection Refused or Timeout

• Cause: Using direct IPv6 connection or wrong pooler port.
• Fix: Use Supabase's Session Pooler string (usually port 5432 or 6543) with pool_pre_ping=True. If your ISP has IPv6 resolution issues, the pooler hostname resolves via IPv4 reliably.

2. LiveKit Voice Call Fails to Connect

• Cause: Browser permissions or mismatched LIVEKIT_URL.
• Fix: Ensure microphone permissions are granted in the browser. In .env, check that LIVEKIT_URL starts with wss:// and credentials match your LiveKit Cloud dashboard.

3. Missing pgvector Extension Error

• Cause: Database user lacks permissions or extension not toggled.
• Fix: Log in to your Supabase SQL Editor and execute:

  CREATE EXTENSION IF NOT EXISTS vector;
  

4. Port 8000 or 5173 Already in Use

• Fix (Windows PowerShell):

  # Find and kill process on port 8000
  Get-Process -Id (Get-NetTCPConnection -LocalPort 8000).OwningProcess | Stop-Process -Force
  

---

👥 Contributors & Support

• Author: Dinod imanjith (GitHub: @dinod001)
• Project: FinVox — Final Year Research Project in AI & Multi-Agent Financial Engineering.
• License: MIT License.