@vezlo/assistant-server 1.0.0 → 1.1.0

package/README.md

@@ -32,63 +32,110 @@ cd assistant-server
 npm install
 ```
 
-## 🚀 Quick Start
+## 🚀 Quick Start (Interactive Setup)
 
 ### Prerequisites
 - Node.js 20+ and npm 9+
-- Supabase project with vector extension
+- Supabase project (or PostgreSQL database)
 - OpenAI API key
 
-### 1. Setup Environment
+### Easy Setup with Interactive Wizard
+
+The fastest way to get started is with our interactive setup wizard:
 
 ```bash
-# If installed via npm, create a project directory
-mkdir my-ai-assistant
-cd my-ai-assistant
+# If installed globally
+vezlo-setup
 
-# Copy example environment file
-cp node_modules/@vezlo/assistant-server/env.example .env
+# If installed locally
+npx vezlo-setup
 
 # Or if cloned from GitHub
+npm run setup
+```
+
+The wizard will guide you through:
+1. **Database Configuration** - Choose Supabase or PostgreSQL
+2. **OpenAI API Setup** - Configure your AI model
+3. **Automatic Table Creation** - Creates all required database tables
+4. **Environment File Generation** - Saves configuration to .env
+
+After setup completes, start the server:
+
+```bash
+vezlo-server
+```
+
+### Manual Setup (Advanced)
+
+If you prefer manual configuration:
+
+#### 1. Create Environment File
+
+```bash
+# Copy example file
 cp env.example .env
 
-# Edit .env with your credentials (see Environment Configuration below)
+# Edit with your credentials
+nano .env
 ```
 
-### 2. Setup Database
+#### 2. Configure Database
+
+Get your Supabase credentials from:
+- **Dashboard** → Settings → API
+- **Database** → Settings → Connection string
 
-Run the database schema in your Supabase SQL Editor:
+```env
+# Supabase Configuration
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_KEY=your-service-role-key
+SUPABASE_DB_HOST=db.your-project.supabase.co
+SUPABASE_DB_PASSWORD=your-database-password
+
+# OpenAI Configuration
+OPENAI_API_KEY=sk-your-api-key
+```
+
+#### 3. Setup Database Tables
+
+**Option A: Automated Setup**
 ```bash
-# Copy from package installation
-cat node_modules/@vezlo/assistant-server/database-schema.sql
+vezlo-setup  # Run wizard and choose option 3 to use existing .env
+```
 
-# Or from cloned repo
+**Option B: Manual SQL**
+```bash
+# Copy schema to Supabase SQL Editor
 cat database-schema.sql
+
+# Then execute in Supabase Dashboard → SQL Editor
 ```
 
-### 3. Start the Server
+#### 4. Validate Setup
+
+```bash
+# Verify database connection and tables
+vezlo-validate
+
+# Or with npm
+npm run validate
+```
+
+#### 5. Start Server
 
 ```bash
 # If installed globally
 vezlo-server
 
-# If installed locally in project
+# If installed locally
 npx vezlo-server
 
-# Or if cloned from GitHub
+# Or from source
 npm run build && npm start
 ```
 
-### 4. Verify Installation
-```bash
-# Health check
-curl http://localhost:3000/health
-
-# API documentation
-open http://localhost:3000/docs
-```
-
-### 5. Docker Deployment (Optional)
+### Docker Deployment
 
 ```bash
 # Start with Docker Compose
@@ -135,6 +182,28 @@ CHUNK_SIZE=1000
 CHUNK_OVERLAP=200
 ```
 
+## 🔧 CLI Commands
+
+The package provides these command-line tools:
+
+### vezlo-setup
+Interactive wizard for initial configuration and database setup.
+```bash
+vezlo-setup
+```
+
+### vezlo-validate
+Validates database connection and verifies all tables exist.
+```bash
+vezlo-validate
+```
+
+### vezlo-server
+Starts the API server.
+```bash
+vezlo-server
+```
+
 ## 📚 API Documentation
 
 ### Base URL

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@vezlo/assistant-server",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Production-ready AI Assistant Server with vector search, conversation management, and real-time communication",
   "main": "dist/server.js",
   "types": "dist/server.d.ts",
   "bin": {
-    "vezlo-server": "./bin/vezlo-server.js"
+    "vezlo-server": "./bin/vezlo-server.js",
+    "vezlo-setup": "./scripts/setup.js",
+    "vezlo-validate": "./scripts/validate-db.js"
   },
   "files": [
     "dist/",
     "bin/",
+    "scripts/",
     "database-schema.sql",
     "knexfile.ts",
     "env.example",
@@ -22,6 +25,8 @@
     "build": "tsc",
     "start": "node dist/server.js",
     "prepublishOnly": "npm run build",
+    "setup": "node scripts/setup.js",
+    "validate": "node scripts/validate-db.js",
     "migrate:make": "knex migrate:make",
     "migrate:latest": "knex migrate:latest",
     "migrate:rollback": "knex migrate:rollback",

package/scripts/entrypoint.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+# Migration runner script for Docker
+# This script runs database migrations before starting the application
+
+set -e
+
+echo "Starting Vezlo Server with Database Migrations..."
+
+# Wait for database to be ready (optional)
+echo "Waiting for database connection..."
+sleep 2
+
+# Run migrations
+echo "Running database migrations..."
+npm run migrate:latest
+
+# Start the application
+echo "Starting Vezlo Server..."
+exec "$@"
+

package/scripts/setup.js

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+
+/**
+ * Vezlo Assistant Server Setup Wizard
+ * Interactive CLI to configure database and environment
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { createClient } = require('@supabase/supabase-js');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+// ANSI color codes
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function question(prompt) {
+  return new Promise(resolve => {
+    rl.question(`${colors.cyan}${prompt}${colors.reset} `, resolve);
+  });
+}
+
+async function main() {
+  console.clear();
+  log('\n🚀 Vezlo Assistant Server Setup Wizard\n', 'bright');
+  log('This wizard will help you configure your server in 3 easy steps:\n', 'blue');
+  log('  1. Database Connection (Supabase or PostgreSQL)');
+  log('  2. OpenAI API Configuration');
+  log('  3. Automatic Table Creation\n');
+
+  // Step 1: Database Type Selection
+  log('\n═══════════════════════════════════════════════════════════', 'cyan');
+  log('  STEP 1: Database Configuration', 'bright');
+  log('═══════════════════════════════════════════════════════════\n', 'cyan');
+
+  log('Choose your database type:');
+  log('  [1] Supabase (Recommended)');
+  log('  [2] PostgreSQL (Direct Connection)');
+  log('  [3] Use existing .env file\n');
+
+  const dbChoice = await question('Enter your choice (1-3):');
+
+  let config = {};
+
+  if (dbChoice === '1') {
+    config = await setupSupabase();
+  } else if (dbChoice === '2') {
+    config = await setupPostgreSQL();
+  } else if (dbChoice === '3') {
+    config = await loadExistingConfig();
+  } else {
+    log('\n❌ Invalid choice. Exiting...', 'red');
+    rl.close();
+    return;
+  }
+
+  // Step 2: OpenAI Configuration
+  log('\n═══════════════════════════════════════════════════════════', 'cyan');
+  log('  STEP 2: OpenAI API Configuration', 'bright');
+  log('═══════════════════════════════════════════════════════════\n', 'cyan');
+
+  const openaiKey = await question('Enter your OpenAI API key (sk-...):');
+  config.OPENAI_API_KEY = openaiKey.trim();
+
+  const aiModel = await question('AI Model (default: gpt-4o):') || 'gpt-4o';
+  config.AI_MODEL = aiModel.trim();
+
+  // Step 3: Save Configuration
+  log('\n═══════════════════════════════════════════════════════════', 'cyan');
+  log('  STEP 3: Save Configuration', 'bright');
+  log('═══════════════════════════════════════════════════════════\n', 'cyan');
+
+  const envPath = path.join(process.cwd(), '.env');
+  await saveEnvFile(envPath, config);
+
+  log('\n✅ Configuration saved to .env', 'green');
+
+  // Step 4: Database Setup
+  log('\n═══════════════════════════════════════════════════════════', 'cyan');
+  log('  STEP 4: Database Setup', 'bright');
+  log('═══════════════════════════════════════════════════════════\n', 'cyan');
+
+  const setupDb = await question('Setup database tables now? (y/n):');
+
+  if (setupDb.toLowerCase() === 'y') {
+    await setupDatabase(config);
+  } else {
+    log('\n⚠️  Skipping database setup.', 'yellow');
+    log('   Run "npx vezlo-setup-db" later to create tables.\n', 'yellow');
+  }
+
+  // Final Instructions
+  log('\n═══════════════════════════════════════════════════════════', 'green');
+  log('  🎉 Setup Complete!', 'bright');
+  log('═══════════════════════════════════════════════════════════\n', 'green');
+
+  log('Next steps:');
+  log('  1. Review your .env file');
+  log('  2. Start the server: ' + colors.bright + 'vezlo-server' + colors.reset);
+  log('  3. Visit: ' + colors.bright + 'http://localhost:3000/health' + colors.reset);
+  log('  4. API docs: ' + colors.bright + 'http://localhost:3000/docs' + colors.reset + '\n');
+
+  rl.close();
+}
+
+async function setupSupabase() {
+  log('\n📦 Supabase Configuration\n', 'blue');
+  log('You can find these values in your Supabase Dashboard:', 'yellow');
+  log('  Settings > API > Project URL & API Keys\n', 'yellow');
+
+  const supabaseUrl = await question('Supabase Project URL (https://xxx.supabase.co):');
+  const supabaseAnonKey = await question('Supabase Anon Key:');
+  const supabaseServiceKey = await question('Supabase Service Role Key:');
+
+  // Validate connection
+  log('\n🔄 Testing connection...', 'yellow');
+
+  try {
+    const client = createClient(supabaseUrl.trim(), supabaseServiceKey.trim());
+    const { data, error } = await client.from('_test').select('*').limit(1);
+
+    // This will fail but confirms we can connect
+    if (error && error.code !== 'PGRST204' && error.code !== '42P01') {
+      log(`\n⚠️  Warning: ${error.message}`, 'yellow');
+      log('Continuing with setup...\n', 'yellow');
+    } else {
+      log('✅ Connection successful!\n', 'green');
+    }
+  } catch (err) {
+    log(`\n⚠️  Warning: Could not verify connection`, 'yellow');
+    log('Continuing with setup...\n', 'yellow');
+  }
+
+  // Extract database connection info from Supabase URL
+  const projectId = supabaseUrl.match(/https:\/\/(.+?)\.supabase\.co/)?.[1];
+  const dbHost = projectId ? `db.${projectId}.supabase.co` : '';
+
+  log('Database connection details:', 'blue');
+  log(`  Host: ${dbHost}`);
+  log(`  Port: 5432`);
+  log(`  Database: postgres`);
+  log(`  User: postgres\n`);
+
+  const dbPassword = await question('Supabase Database Password (from Settings > Database):');
+
+  return {
+    SUPABASE_URL: supabaseUrl.trim(),
+    SUPABASE_ANON_KEY: supabaseAnonKey.trim(),
+    SUPABASE_SERVICE_KEY: supabaseServiceKey.trim(),
+    SUPABASE_DB_HOST: dbHost,
+    SUPABASE_DB_PORT: '5432',
+    SUPABASE_DB_NAME: 'postgres',
+    SUPABASE_DB_USER: 'postgres',
+    SUPABASE_DB_PASSWORD: dbPassword.trim(),
+    PORT: '3000',
+    NODE_ENV: 'development',
+    CORS_ORIGINS: 'http://localhost:3000,http://localhost:5173'
+  };
+}
+
+async function setupPostgreSQL() {
+  log('\n🗄️  PostgreSQL Configuration\n', 'blue');
+
+  const host = await question('Database Host (localhost):') || 'localhost';
+  const port = await question('Database Port (5432):') || '5432';
+  const database = await question('Database Name (postgres):') || 'postgres';
+  const user = await question('Database User (postgres):') || 'postgres';
+  const password = await question('Database Password:');
+
+  return {
+    SUPABASE_DB_HOST: host.trim(),
+    SUPABASE_DB_PORT: port.trim(),
+    SUPABASE_DB_NAME: database.trim(),
+    SUPABASE_DB_USER: user.trim(),
+    SUPABASE_DB_PASSWORD: password.trim(),
+    PORT: '3000',
+    NODE_ENV: 'development',
+    CORS_ORIGINS: 'http://localhost:3000,http://localhost:5173'
+  };
+}
+
+async function loadExistingConfig() {
+  const envPath = path.join(process.cwd(), '.env');
+
+  if (!fs.existsSync(envPath)) {
+    log('\n❌ No .env file found in current directory', 'red');
+    throw new Error('.env file not found');
+  }
+
+  log('\n✅ Loading configuration from .env\n', 'green');
+
+  const envContent = fs.readFileSync(envPath, 'utf8');
+  const config = {};
+
+  envContent.split('\n').forEach(line => {
+    const match = line.match(/^([^=:#]+)=(.*)$/);
+    if (match) {
+      const key = match[1].trim();
+      const value = match[2].trim();
+      config[key] = value;
+    }
+  });
+
+  return config;
+}
+
+async function saveEnvFile(envPath, config) {
+  const envContent = `# Vezlo Assistant Server Configuration
+# Generated by setup wizard on ${new Date().toISOString()}
+
+# Server Configuration
+PORT=${config.PORT || '3000'}
+NODE_ENV=${config.NODE_ENV || 'development'}
+LOG_LEVEL=info
+
+# CORS Configuration
+CORS_ORIGINS=${config.CORS_ORIGINS || 'http://localhost:3000,http://localhost:5173'}
+
+# Rate Limiting
+RATE_LIMIT_WINDOW=60000
+RATE_LIMIT_MAX=100
+
+# Supabase Configuration
+${config.SUPABASE_URL ? `SUPABASE_URL=${config.SUPABASE_URL}` : '# SUPABASE_URL=https://your-project.supabase.co'}
+${config.SUPABASE_ANON_KEY ? `SUPABASE_ANON_KEY=${config.SUPABASE_ANON_KEY}` : '# SUPABASE_ANON_KEY=your-anon-key'}
+${config.SUPABASE_SERVICE_KEY ? `SUPABASE_SERVICE_KEY=${config.SUPABASE_SERVICE_KEY}` : '# SUPABASE_SERVICE_KEY=your-service-role-key'}
+
+# Database Configuration
+SUPABASE_DB_HOST=${config.SUPABASE_DB_HOST || 'localhost'}
+SUPABASE_DB_PORT=${config.SUPABASE_DB_PORT || '5432'}
+SUPABASE_DB_NAME=${config.SUPABASE_DB_NAME || 'postgres'}
+SUPABASE_DB_USER=${config.SUPABASE_DB_USER || 'postgres'}
+SUPABASE_DB_PASSWORD=${config.SUPABASE_DB_PASSWORD || ''}
+
+# OpenAI Configuration
+OPENAI_API_KEY=${config.OPENAI_API_KEY || 'sk-your-openai-api-key'}
+AI_MODEL=${config.AI_MODEL || 'gpt-4o'}
+AI_TEMPERATURE=0.7
+AI_MAX_TOKENS=1000
+
+# Organization Settings
+ORGANIZATION_NAME=Vezlo
+ASSISTANT_NAME=Vezlo Assistant
+
+# Knowledge Base
+CHUNK_SIZE=1000
+CHUNK_OVERLAP=200
+`;
+
+  fs.writeFileSync(envPath, envContent, 'utf8');
+}
+
+async function setupDatabase(config) {
+  log('\n🔄 Setting up database tables...', 'yellow');
+
+  try {
+    const { Client } = require('pg');
+
+    const client = new Client({
+      host: config.SUPABASE_DB_HOST,
+      port: parseInt(config.SUPABASE_DB_PORT || '5432'),
+      database: config.SUPABASE_DB_NAME,
+      user: config.SUPABASE_DB_USER,
+      password: config.SUPABASE_DB_PASSWORD,
+      ssl: { rejectUnauthorized: false }
+    });
+
+    await client.connect();
+    log('✅ Connected to database', 'green');
+
+    // Read schema file
+    const schemaPath = path.join(__dirname, '..', 'database-schema.sql');
+
+    if (!fs.existsSync(schemaPath)) {
+      log('❌ database-schema.sql not found', 'red');
+      return;
+    }
+
+    const schema = fs.readFileSync(schemaPath, 'utf8');
+
+    log('🔄 Creating tables...', 'yellow');
+    await client.query(schema);
+
+    log('✅ Database tables created successfully!', 'green');
+
+    // Verify tables
+    const result = await client.query(`
+      SELECT table_name
+      FROM information_schema.tables
+      WHERE table_schema = 'public'
+      AND table_name IN ('conversations', 'messages', 'message_feedback', 'knowledge_items')
+      ORDER BY table_name
+    `);
+
+    log('\n📊 Verified tables:', 'blue');
+    result.rows.forEach(row => {
+      log(`   ✓ ${row.table_name}`, 'green');
+    });
+    log('');
+
+    await client.end();
+
+  } catch (error) {
+    log(`\n❌ Database setup failed: ${error.message}`, 'red');
+    log('\nYou can manually run the setup later:', 'yellow');
+    log('  1. Copy database-schema.sql to your Supabase SQL Editor', 'yellow');
+    log('  2. Execute the SQL to create tables\n', 'yellow');
+  }
+}
+
+// Handle errors and cleanup
+process.on('SIGINT', () => {
+  log('\n\n⚠️  Setup cancelled by user', 'yellow');
+  rl.close();
+  process.exit(0);
+});
+
+// Run the wizard
+main().catch(error => {
+  log(`\n❌ Setup failed: ${error.message}`, 'red');
+  rl.close();
+  process.exit(1);
+});

package/scripts/validate-db.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+/**
+ * Vezlo Assistant Server - Database Validation
+ * Validates database connection and table setup
+ */
+
+const dotenv = require('dotenv');
+const { createClient } = require('@supabase/supabase-js');
+
+// Load environment variables
+dotenv.config();
+
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  bright: '\x1b[1m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+async function validateDatabase() {
+  log('\n🔍 Validating Database Configuration\n', 'cyan');
+
+  // Check environment variables
+  log('Checking environment variables...', 'yellow');
+
+  const requiredVars = [
+    'SUPABASE_URL',
+    'SUPABASE_SERVICE_KEY',
+    'SUPABASE_DB_HOST',
+    'SUPABASE_DB_PASSWORD'
+  ];
+
+  const missing = requiredVars.filter(key => !process.env[key]);
+
+  if (missing.length > 0) {
+    log(`\n❌ Missing required environment variables:`, 'red');
+    missing.forEach(key => log(`   - ${key}`, 'red'));
+    log('\nRun the setup wizard: ' + colors.bright + 'npx vezlo-setup' + colors.reset + '\n', 'yellow');
+    process.exit(1);
+  }
+
+  log('✅ Environment variables configured\n', 'green');
+
+  // Test Supabase connection
+  log('Testing Supabase connection...', 'yellow');
+
+  try {
+    const supabase = createClient(
+      process.env.SUPABASE_URL,
+      process.env.SUPABASE_SERVICE_KEY
+    );
+
+    // Try to query a table
+    const { error } = await supabase.from('conversations').select('count').limit(0);
+
+    if (error && error.code !== 'PGRST116') {
+      throw error;
+    }
+
+    log('✅ Supabase connection successful\n', 'green');
+
+  } catch (error) {
+    log(`❌ Supabase connection failed: ${error.message}\n`, 'red');
+    process.exit(1);
+  }
+
+  // Test database connection and validate tables
+  log('Validating database tables...', 'yellow');
+
+  try {
+    const { Client } = require('pg');
+
+    const client = new Client({
+      host: process.env.SUPABASE_DB_HOST,
+      port: parseInt(process.env.SUPABASE_DB_PORT || '5432'),
+      database: process.env.SUPABASE_DB_NAME || 'postgres',
+      user: process.env.SUPABASE_DB_USER || 'postgres',
+      password: process.env.SUPABASE_DB_PASSWORD,
+      ssl: { rejectUnauthorized: false }
+    });
+
+    await client.connect();
+
+    // Check required tables
+    const requiredTables = [
+      'conversations',
+      'messages',
+      'message_feedback',
+      'knowledge_items'
+    ];
+
+    const result = await client.query(`
+      SELECT table_name
+      FROM information_schema.tables
+      WHERE table_schema = 'public'
+      AND table_name = ANY($1)
+      ORDER BY table_name
+    `, [requiredTables]);
+
+    const existingTables = result.rows.map(row => row.table_name);
+    const missingTables = requiredTables.filter(t => !existingTables.includes(t));
+
+    if (missingTables.length > 0) {
+      log(`\n❌ Missing required tables:`, 'red');
+      missingTables.forEach(table => log(`   - ${table}`, 'red'));
+      log('\nRun the setup wizard: ' + colors.bright + 'npx vezlo-setup' + colors.reset + '\n', 'yellow');
+      await client.end();
+      process.exit(1);
+    }
+
+    log('✅ All required tables exist\n', 'green');
+
+    // Check table structure
+    log('Checking table structure...', 'yellow');
+
+    const schemaCheck = await client.query(`
+      SELECT
+        t.table_name,
+        COUNT(c.column_name) as column_count
+      FROM information_schema.tables t
+      LEFT JOIN information_schema.columns c
+        ON c.table_name = t.table_name
+        AND c.table_schema = t.table_schema
+      WHERE t.table_schema = 'public'
+      AND t.table_name = ANY($1)
+      GROUP BY t.table_name
+      ORDER BY t.table_name
+    `, [requiredTables]);
+
+    log('\n📊 Table Structure:', 'cyan');
+    schemaCheck.rows.forEach(row => {
+      log(`   ✓ ${row.table_name} (${row.column_count} columns)`, 'green');
+    });
+
+    // Check for vector extension
+    const vectorCheck = await client.query(`
+      SELECT EXISTS(
+        SELECT 1 FROM pg_extension WHERE extname = 'vector'
+      ) as has_vector
+    `);
+
+    if (vectorCheck.rows[0].has_vector) {
+      log('   ✓ pgvector extension enabled', 'green');
+    } else {
+      log('   ⚠️  pgvector extension not enabled (semantic search disabled)', 'yellow');
+    }
+
+    log('\n✅ Database validation complete!\n', 'green');
+    log('Your server is ready to start:', 'cyan');
+    log('  ' + colors.bright + 'vezlo-server' + colors.reset + '\n');
+
+    await client.end();
+
+  } catch (error) {
+    log(`\n❌ Database validation failed: ${error.message}\n`, 'red');
+    process.exit(1);
+  }
+}
+
+// Run validation
+validateDatabase().catch(error => {
+  log(`\n❌ Validation failed: ${error.message}\n`, 'red');
+  process.exit(1);
+});