@vezlo/assistant-server 1.0.0

package/README.md

@@ -0,0 +1,432 @@
+# Vezlo AI Assistant Server
+
+🚀 **Production-ready Node.js/TypeScript API server** for the Vezlo AI Assistant platform - Complete backend APIs with Docker deployment and database migrations.
+
+## 🏗️ Architecture
+
+- **Backend APIs** - RESTful API endpoints for AI chat and knowledge management
+- **Real-time Communication** - WebSocket support for live chat
+- **Vector Search** - Supabase-powered semantic search with embeddings
+- **Conversation Management** - Persistent conversation history
+- **Feedback System** - Message rating and improvement tracking
+- **Database Migrations** - Knex.js migration system for schema management
+- **Production Ready** - Docker containerization with health checks
+
+## 📦 Installation
+
+### Option 1: Install from npm (Recommended)
+
+```bash
+# Install globally
+npm install -g @vezlo/assistant-server
+
+# Or install in your project
+npm install @vezlo/assistant-server
+```
+
+### Option 2: Clone from GitHub
+
+```bash
+git clone https://github.com/vezlo/assistant-server.git
+cd assistant-server
+npm install
+```
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Node.js 20+ and npm 9+
+- Supabase project with vector extension
+- OpenAI API key
+
+### 1. Setup Environment
+
+```bash
+# If installed via npm, create a project directory
+mkdir my-ai-assistant
+cd my-ai-assistant
+
+# Copy example environment file
+cp node_modules/@vezlo/assistant-server/env.example .env
+
+# Or if cloned from GitHub
+cp env.example .env
+
+# Edit .env with your credentials (see Environment Configuration below)
+```
+
+### 2. Setup Database
+
+Run the database schema in your Supabase SQL Editor:
+```bash
+# Copy from package installation
+cat node_modules/@vezlo/assistant-server/database-schema.sql
+
+# Or from cloned repo
+cat database-schema.sql
+```
+
+### 3. Start the Server
+
+```bash
+# If installed globally
+vezlo-server
+
+# If installed locally in project
+npx vezlo-server
+
+# Or if cloned from GitHub
+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)
+
+```bash
+# Start with Docker Compose
+docker-compose up -d
+
+# View logs
+docker-compose logs -f vezlo-server
+```
+
+## 🔧 Environment Configuration
+
+Edit `.env` file with your credentials:
+
+```bash
+# REQUIRED - Supabase Configuration
+SUPABASE_URL=https://your-project-id.supabase.co
+SUPABASE_ANON_KEY=your-anon-key
+SUPABASE_SERVICE_KEY=your-service-role-key
+
+# REQUIRED - OpenAI Configuration
+OPENAI_API_KEY=sk-your-openai-api-key
+AI_MODEL=gpt-4o
+AI_TEMPERATURE=0.7
+AI_MAX_TOKENS=1000
+
+# OPTIONAL - Server Configuration
+PORT=3000
+NODE_ENV=production
+LOG_LEVEL=info
+
+# OPTIONAL - CORS Configuration
+CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# OPTIONAL - Rate Limiting
+RATE_LIMIT_WINDOW=60000
+RATE_LIMIT_MAX=100
+
+# OPTIONAL - Organization Settings
+ORGANIZATION_NAME=Vezlo
+ASSISTANT_NAME=Vezlo Assistant
+
+# OPTIONAL - Knowledge Base
+CHUNK_SIZE=1000
+CHUNK_OVERLAP=200
+```
+
+## 📚 API Documentation
+
+### Base URL
+```
+http://localhost:3000/api
+```
+
+### Interactive Documentation
+- **Swagger UI**: `http://localhost:3000/docs`
+- **Health Check**: `http://localhost:3000/health`
+
+### Core Endpoints
+
+#### Conversations
+- `POST /api/conversations` - Create new conversation
+- `GET /api/conversations/:uuid` - Get conversation with messages
+- `DELETE /api/conversations/:uuid` - Delete conversation
+- `GET /api/users/:uuid/conversations` - Get user conversations
+
+#### Messages
+- `POST /api/conversations/:uuid/messages` - Create user message
+- `POST /api/messages/:uuid/generate` - Generate AI response
+
+#### Knowledge Base
+- `POST /api/knowledge/items` - Create knowledge item
+- `GET /api/knowledge/items` - List knowledge items
+- `GET /api/knowledge/items/:uuid` - Get knowledge item
+- `PUT /api/knowledge/items/:uuid` - Update knowledge item
+- `DELETE /api/knowledge/items/:uuid` - Delete knowledge item
+- `POST /api/knowledge/search` - Search knowledge base
+
+#### Feedback
+- `POST /api/feedback` - Submit message feedback
+
+### WebSocket Events
+- `join-conversation` - Join conversation room
+- `conversation:message` - Real-time message updates
+
+## 💬 Conversation 2-API Flow
+
+The conversation system follows the industry-standard **2-API flow** pattern for AI chat applications:
+
+### 1. Create User Message
+```bash
+POST /api/conversations/{conversation-uuid}/messages
+```
+**Purpose**: Store the user's message in the conversation
+**Response**: Returns the user message with UUID
+
+### 2. Generate AI Response  
+```bash
+POST /api/messages/{message-uuid}/generate
+```
+**Purpose**: Generate AI response based on the user message
+**Response**: Returns the AI assistant's response
+
+### Why 2-API Flow?
+
+This pattern is the **global recognized standard** because:
+
+✅ **Separation of Concerns**
+- User message storage is separate from AI generation
+- Allows for message persistence even if AI generation fails
+- Enables message history and conversation management
+
+✅ **Reliability & Error Handling**
+- User messages are saved immediately
+- AI generation can be retried independently
+- Partial failures don't lose user input
+
+✅ **Scalability**
+- AI generation can be queued/processed asynchronously
+- Different rate limits for storage vs generation
+- Enables streaming responses and real-time updates
+
+✅ **Industry Standard**
+- Used by OpenAI, Anthropic, Google, and other major AI platforms
+- Familiar pattern for developers
+- Enables advanced features like message regeneration, threading, and branching
+
+### Example Flow:
+```bash
+# 1. User sends message
+curl -X POST /api/conversations/abc123/messages \
+  -d '{"content": "How do I integrate your API?"}'
+# Response: {"uuid": "msg456", "content": "How do I integrate your API?", ...}
+
+# 2. Generate AI response
+curl -X POST /api/messages/msg456/generate \
+  -d '{}'
+# Response: {"uuid": "msg789", "content": "To integrate our API...", ...}
+```
+
+## 🗄️ Database Setup
+
+Run the SQL schema in your Supabase SQL Editor:
+
+```bash
+# Copy the database schema file
+cp database-schema.sql /path/to/your/supabase/sql-editor
+```
+
+The `database-schema.sql` file contains all necessary tables and functions:
+- **conversations** - Chat conversation management
+- **messages** - Individual messages within conversations  
+- **message_feedback** - User feedback on messages
+- **knowledge_items** - Knowledge base items with vector embeddings
+- **match_knowledge_items()** - Vector similarity search function
+
+## 🐳 Docker Commands
+
+```bash
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f vezlo-server
+
+# Stop services
+docker-compose down
+
+# Rebuild and start
+docker-compose up -d --build
+
+# View running containers
+docker-compose ps
+
+# Access container shell
+docker exec -it vezlo-server sh
+```
+
+## 🧪 Testing the API
+
+### Health Check
+```bash
+curl http://localhost:3000/health
+```
+
+### Complete Conversation Flow
+```bash
+# 1. Create conversation
+CONV_UUID=$(curl -X POST http://localhost:3000/api/conversations \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Test Conversation", "user_uuid": 12345, "company_uuid": 67890}' \
+  | jq -r '.uuid')
+
+# 2. Send user message
+MSG_UUID=$(curl -X POST http://localhost:3000/api/conversations/$CONV_UUID/messages \
+  -H "Content-Type: application/json" \
+  -d '{"content": "Hello, how can you help me?"}' \
+  | jq -r '.uuid')
+
+# 3. Generate AI response
+curl -X POST http://localhost:3000/api/messages/$MSG_UUID/generate \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+### Search Knowledge Base
+```bash
+curl -X POST http://localhost:3000/api/knowledge/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "How to use the API?",
+    "limit": 5,
+    "threshold": 0.7,
+    "type": "hybrid"
+  }'
+```
+
+## 🔧 Development
+
+### Local Development Setup
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Start development server
+npm run dev
+
+# Run tests
+npm test
+```
+
+### Project Structure
+```
+vezlo/
+├── docs/                # Documentation
+│   ├── DEVELOPER_GUIDELINES.md
+│   └── MIGRATIONS.md
+├── src/
+│   ├── config/          # Configuration files
+│   ├── controllers/     # API route handlers
+│   ├── middleware/      # Express middleware
+│   ├── schemas/         # API request/response schemas
+│   ├── services/        # Business logic services
+│   ├── storage/         # Database repositories
+│   ├── types/           # TypeScript type definitions
+│   ├── migrations/      # Database migrations
+│   └── server.ts        # Main application entry
+├── scripts/             # Utility scripts
+├── Dockerfile           # Production container
+├── docker-compose.yml   # Docker Compose configuration
+├── knexfile.ts          # Database configuration
+├── env.example          # Environment template
+├── package.json         # Dependencies and scripts
+└── tsconfig.json        # TypeScript configuration
+```
+
+## 🚀 Production Deployment
+
+### Environment Variables
+Ensure all required environment variables are set:
+- `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` (required)
+- `OPENAI_API_KEY` (required)
+- `NODE_ENV=production`
+- `CORS_ORIGINS` (set to your domain)
+
+### Docker Production
+```bash
+# Build production image
+docker build -t vezlo-server .
+
+# Run production container
+docker run -d \
+  --name vezlo-server \
+  -p 3000:3000 \
+  --env-file .env \
+  vezlo-server
+```
+
+### Health Monitoring
+- Health check endpoint: `/health`
+- Docker health check configured
+- Logs available in `./logs/` directory
+
+## 🤝 Contributing
+
+### Development Workflow
+1. Fork the repository
+2. Create feature branch: `git checkout -b feature/new-feature`
+3. Make changes and test locally
+4. Run tests: `npm test`
+5. Commit: `git commit -m 'Add new feature'`
+6. Push: `git push origin feature/new-feature`
+7. Submit pull request
+
+### Code Standards
+- **TypeScript** - Full type safety required
+- **ESLint** - Code formatting and quality
+- **Prettier** - Consistent code style
+- **Tests** - Unit tests for new features
+- **Documentation** - Update README for API changes
+
+### API Development
+- Follow RESTful conventions
+- Use proper HTTP status codes
+- Include comprehensive error handling
+- Update Swagger documentation
+- Add request/response schemas
+
+## 📊 Performance & Security
+
+### Performance
+- **Response Time**: Optimized for fast API responses
+- **Concurrent Users**: Supports multiple concurrent users
+- **Memory Usage**: Efficient memory management
+- **Database**: Supabase vector operations integration
+
+### Security Features
+- **Rate Limiting** - Configurable request limits
+- **CORS Protection** - Configurable origins
+- **Input Validation** - Request schema validation
+- **Error Handling** - Secure error responses
+- **Health Monitoring** - Application logs and Docker health checks
+
+## 📚 Documentation
+
+- **[Developer Guidelines](docs/DEVELOPER_GUIDELINES.md)** - Development workflow, coding standards, and best practices
+- **[Database Migrations](docs/MIGRATIONS.md)** - Complete guide to Knex.js migration system
+- **[API Documentation](http://localhost:3000/docs)** - Interactive Swagger documentation (when running)
+
+## 📄 License
+
+This project is dual-licensed:
+
+- **Non-Commercial Use**: Free under AGPL-3.0 license
+- **Commercial Use**: Requires a commercial license - contact us for details
+
+---
+
+**Status**: ✅ Production Ready | **Version**: 1.0.0 | **Node.js**: 20+ | **TypeScript**: 5+

package/bin/vezlo-server.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+/**
+ * Vezlo Assistant Server CLI
+ * Starts the AI assistant server with environment configuration
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// Check if server is built
+const serverPath = path.join(__dirname, '..', 'dist', 'server.js');
+
+if (!fs.existsSync(serverPath)) {
+  console.error('❌ Error: Server not built. Please run "npm run build" first.');
+  console.error('');
+  console.error('If you installed via npm, try reinstalling:');
+  console.error('  npm install -g @vezlo/assistant-server');
+  process.exit(1);
+}
+
+// Display startup banner
+console.log('');
+console.log('🚀 Starting Vezlo Assistant Server...');
+console.log('');
+
+// Check for .env file
+const envPath = path.join(process.cwd(), '.env');
+if (!fs.existsSync(envPath)) {
+  console.warn('⚠️  Warning: No .env file found in current directory');
+  console.warn('   Copy env.example to .env and configure your settings');
+  console.warn('');
+}
+
+// Start the server
+require(serverPath);

package/database-schema.sql

@@ -0,0 +1,154 @@
+-- Vezlo AI Assistant - Modern Database Schema
+-- Finalized schema with conversation-based chat and unified knowledge base
+-- Run this in your Supabase SQL Editor
+
+-- Enable required extensions
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- ============================================================================
+-- CONVERSATIONS & MESSAGES SCHEMA (Modern 2-API Flow)
+-- ============================================================================
+
+-- Conversations table (renamed from chat_sessions)
+CREATE TABLE IF NOT EXISTS conversations (
+  id BIGSERIAL PRIMARY KEY,
+  uuid UUID DEFAULT gen_random_uuid() UNIQUE NOT NULL,
+  company_id BIGINT,                        -- Multi-tenancy support
+  creator_id BIGINT NOT NULL,               -- User who created conversation
+  title TEXT NOT NULL,
+  message_count INTEGER DEFAULT 0,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW(),
+  deleted_at TIMESTAMPTZ                    -- Soft delete
+);
+
+-- Messages table (supports parent-child relationships for regeneration)
+CREATE TABLE IF NOT EXISTS messages (
+  id BIGSERIAL PRIMARY KEY,
+  uuid UUID DEFAULT gen_random_uuid() UNIQUE NOT NULL,
+  conversation_id BIGINT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+  parent_message_id BIGINT REFERENCES messages(id), -- For regeneration chains
+  type TEXT NOT NULL,                       -- user, assistant, system
+  content TEXT NOT NULL,
+  status TEXT DEFAULT 'completed',          -- generating, completed, stopped, failed
+  metadata JSONB DEFAULT '{}',              -- For tool_calls, tool_results, etc.
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Message feedback table
+CREATE TABLE IF NOT EXISTS message_feedback (
+  id BIGSERIAL PRIMARY KEY,
+  uuid UUID DEFAULT gen_random_uuid() UNIQUE NOT NULL,
+  message_id BIGINT NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+  user_id BIGINT NOT NULL,
+  rating TEXT NOT NULL,                     -- positive, negative
+  category TEXT,
+  comment TEXT,
+  suggested_improvement TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- ============================================================================
+-- KNOWLEDGE BASE SCHEMA (Unified Single Table)
+-- ============================================================================
+
+-- Knowledge items table (folders, documents, files, URLs - everything)
+CREATE TABLE IF NOT EXISTS knowledge_items (
+  id BIGSERIAL PRIMARY KEY,
+  uuid UUID DEFAULT gen_random_uuid() UNIQUE NOT NULL,
+  parent_id BIGINT REFERENCES knowledge_items(id), -- Hierarchical structure
+  company_id BIGINT,                        -- Multi-tenancy support
+  title TEXT NOT NULL,
+  description TEXT,
+  type TEXT NOT NULL,                       -- folder, document, file, url, url_directory
+  content TEXT,                             -- For document type
+  file_url TEXT,                            -- For file/url types
+  file_size BIGINT,                         -- File size in bytes
+  file_type TEXT,                           -- MIME type for files
+  metadata JSONB DEFAULT '{}',              -- Flexible metadata storage
+  embedding vector(1536),                  -- OpenAI embeddings for search
+  processed_at TIMESTAMPTZ,                -- When embedding was generated
+  created_by BIGINT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- ============================================================================
+-- INDEXES FOR PERFORMANCE
+-- ============================================================================
+
+-- Conversations indexes
+CREATE INDEX IF NOT EXISTS idx_conversations_uuid ON conversations(uuid);
+CREATE INDEX IF NOT EXISTS idx_conversations_company_id ON conversations(company_id);
+CREATE INDEX IF NOT EXISTS idx_conversations_creator_id ON conversations(creator_id);
+CREATE INDEX IF NOT EXISTS idx_conversations_deleted ON conversations(deleted_at) WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_conversations_updated_at ON conversations(updated_at DESC);
+
+-- Messages indexes
+CREATE INDEX IF NOT EXISTS idx_messages_uuid ON messages(uuid);
+CREATE INDEX IF NOT EXISTS idx_messages_conversation_id ON messages(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_messages_parent_id ON messages(parent_message_id);
+CREATE INDEX IF NOT EXISTS idx_messages_type ON messages(type);
+CREATE INDEX IF NOT EXISTS idx_messages_status ON messages(status);
+CREATE INDEX IF NOT EXISTS idx_messages_created_at ON messages(created_at DESC);
+
+-- Message feedback indexes
+CREATE INDEX IF NOT EXISTS idx_feedback_uuid ON message_feedback(uuid);
+CREATE INDEX IF NOT EXISTS idx_feedback_message_id ON message_feedback(message_id);
+CREATE INDEX IF NOT EXISTS idx_feedback_user_id ON message_feedback(user_id);
+CREATE INDEX IF NOT EXISTS idx_feedback_rating ON message_feedback(rating);
+
+-- Knowledge items indexes
+CREATE INDEX IF NOT EXISTS idx_knowledge_uuid ON knowledge_items(uuid);
+CREATE INDEX IF NOT EXISTS idx_knowledge_company_id ON knowledge_items(company_id);
+CREATE INDEX IF NOT EXISTS idx_knowledge_parent_id ON knowledge_items(parent_id);
+CREATE INDEX IF NOT EXISTS idx_knowledge_type ON knowledge_items(type);
+CREATE INDEX IF NOT EXISTS idx_knowledge_created_by ON knowledge_items(created_by);
+CREATE INDEX IF NOT EXISTS idx_knowledge_created_at ON knowledge_items(created_at DESC);
+
+-- Full-text search index for knowledge items
+CREATE INDEX IF NOT EXISTS idx_knowledge_search 
+ON knowledge_items USING gin(to_tsvector('english', title || ' ' || COALESCE(description, '') || ' ' || COALESCE(content, '')));
+
+-- Vector similarity index for semantic search (only for items with content)
+CREATE INDEX IF NOT EXISTS idx_knowledge_embedding 
+ON knowledge_items USING ivfflat (embedding vector_cosine_ops)
+WHERE embedding IS NOT NULL;
+
+-- Sparse indexes for better performance
+CREATE INDEX IF NOT EXISTS idx_knowledge_content 
+ON knowledge_items(content) WHERE content IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_knowledge_file_url 
+ON knowledge_items(file_url) WHERE file_url IS NOT NULL;
+
+-- ============================================================================
+-- ROW LEVEL SECURITY (Optional but Recommended)
+-- ============================================================================
+
+-- Enable RLS on all tables
+ALTER TABLE conversations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE messages ENABLE ROW LEVEL SECURITY;
+ALTER TABLE message_feedback ENABLE ROW LEVEL SECURITY;
+ALTER TABLE knowledge_items ENABLE ROW LEVEL SECURITY;
+
+-- Policies for service role access (full access)
+CREATE POLICY "Service role can access all conversations" ON conversations
+  FOR ALL USING (auth.role() = 'service_role');
+
+CREATE POLICY "Service role can access all messages" ON messages
+  FOR ALL USING (auth.role() = 'service_role');
+
+CREATE POLICY "Service role can access all feedback" ON message_feedback
+  FOR ALL USING (auth.role() = 'service_role');
+
+CREATE POLICY "Service role can access all knowledge items" ON knowledge_items
+  FOR ALL USING (auth.role() = 'service_role');
+
+-- Example company-based policies (uncomment and modify as needed)
+-- CREATE POLICY "Users can access their company conversations" ON conversations
+--   FOR ALL USING (company_id = auth.jwt() ->> 'company_id');
+
+-- CREATE POLICY "Users can access their company knowledge" ON knowledge_items
+--   FOR ALL USING (company_id = auth.jwt() ->> 'company_id');

package/dist/knexfile.d.ts

@@ -0,0 +1,6 @@
+import type { Knex } from 'knex';
+declare const config: {
+    [key: string]: Knex.Config;
+};
+export default config;
+//# sourceMappingURL=knexfile.d.ts.map

package/dist/knexfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knexfile.d.ts","sourceRoot":"","sources":["../knexfile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAMjC,QAAA,MAAM,MAAM,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;CA4EzC,CAAC;AAEF,eAAe,MAAM,CAAC"}