Technvirons Realtime AI Backend

High-performance async Python backend for real-time AI conversations with Quart, Supabase, and OpenAI.

🚀 Features

• Real-Time Streaming: Low-latency AI responses via WebSockets.
• Session Persistence: automatically saves all conversations to Supabase (PostgreSQL).
• Tool Calling: Real-time integration with Exchange Rate API, JokeAPI, and Open-Meteo.
• Async Architecture: Non-blocking I/O using Quart and asyncio.
• Background Tasks: Automatic session summarization on disconnect.

🛠️ Tech Stack

• Framework: Quart (Async Flask-like)
• Database: Supabase (PostgreSQL)
• AI: OpenAI GPT-4o (Streaming)
• Language: Python 3.11+

⚙️ Setup

1. Install Dependencies:

   pip install -r technvirons-backend/requirements.txt

2. Configure Environment: Create a .env file in technvirons-backend/ with:

   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_KEY=your-service-role-key
   OPENAI_API_KEY=sk-proj-...
   PORT=8000

3. Database Setup:

   

   Sessions Table Data:

   Logs Table Data:

   Run the following SQL in your Supabase SQL Editor to create the required tables:

   CREATE TABLE IF NOT EXISTS sessions (
       id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
       user_id TEXT,
       start_time TIMESTAMPTZ DEFAULT now(),
       end_time TIMESTAMPTZ,
       summary TEXT
   );
   
   CREATE TABLE IF NOT EXISTS logs (
       id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
       session_id UUID REFERENCES sessions(id),
       timestamp TIMESTAMPTZ DEFAULT now(),
       role TEXT,
       content TEXT
   );

4. Run Server:

   python -m uvicorn technvirons-backend.app:app --reload --port 8000

☁️ Deployment (Render)

1. One-Click Deploy:

2. Manual Setup:

   • Create a new Web Service.
   • Connect your GitHub repo.
   • Limit: Root Directory (Leave empty or .).
   • Build Command: pip install -r technvirons-backend/requirements.txt
   • Start Command: uvicorn technvirons-backend.app:app --host 0.0.0.0 --port $PORT
   • Environment Variables: Add SUPABASE_URL, SUPABASE_KEY, OPENAI_API_KEY.

🧪 Testing

Open your browser to: http://localhost:8000/ui to use the built-in test client.

💡 Key Design Choices

1. Framework Selection (Quart): Chosen for its native asyncio support and compatibility with standard Python async libraries (asyncpg, openai async client), which is critical for handling concurrent WebSocket connections and streaming without blocking.
2. State Management: Implemented an in-memory session context (list of messages) within the default WebSocket loop. This ensures low latency access to valid conversation history for the duration of the connection.
3. Database Pattern: Adopted a "Session + Logs" schema. This separates high-level metadata (start/end times, summaries) from high-volume granular event logs, optimizing for both analytical queries (summaries) and audit trails (full logs).
4. Tool Execution: Integrated "Tool Calling" logic directly into the message loop instead of a separate service to keep the architecture monolithic and simpler to deploy/debug for this assignment.

📂 Project Structure

• app.py: Main application and WebSocket routes.
• services.py: Core business logic, AI handling, and tool execution.
• db.py: Database interaction layer (sessions, logs).
• config.py: Environment configuration.
• static/index.html: Simple frontend for testing.