https://github.com/ysocrius/ai-websocket-backend

High-performance async Python backend for real-time AI conversations with Quart, Supabase, and OpenAI.
https://github.com/ysocrius/ai-websocket-backend

llm openai python quart realtime-ai supabase websockets

Last synced: 8 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/ysocrius/ai-websocket-backend
• Owner: ysocrius
• Created: 2025-12-21T09:12:49.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2025-12-21T11:11:49.000Z (6 months ago)
• Last Synced: 2025-12-23T02:12:34.214Z (6 months ago)
• Topics: llm, openai, python, quart, realtime-ai, supabase, websockets
• Language: Python
• Homepage: https://ysocrius.github.io/ai-websocket-backend/
• Size: 672 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Technvirons Realtime AI Backend

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

## 🚀 Features

![App Chat Demo](Screenshots/app_chat.png)

- **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**:

   ```bash

   pip install -r technvirons-backend/requirements.txt

   ```

2. **Configure Environment**:

   Create a `.env` file in `technvirons-backend/` with:

   ```ini

   SUPABASE_URL=https://your-project.supabase.co

   SUPABASE_KEY=your-service-role-key

   OPENAI_API_KEY=sk-proj-...

   PORT=8000

   ```

3. **Database Setup**:

   

   ![Database Schema](Screenshots/db_schema.png)

   

   **Sessions Table Data:**

   ![Sessions Table](Screenshots/session_table.png)

   **Logs Table Data:**

   ![Logs Table](Screenshots/log_table.png)

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

   ```sql

   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**:

   ```bash

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

   ```

## ☁️ Deployment (Render)

1. **One-Click Deploy**:

   [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/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.