Getting Started

This guide will help you set up DriftOS Embed and start routing conversations with embeddings.

Prerequisites

Node.js 18+
Python 3.8+ (for embedding server)
PostgreSQL database

Installation

# Clone and install
git clone https://github.com/DriftOS/driftos-embed
cd driftos-embed
npm install

Configuration

Create your environment file:

cp .env.example .env

Add your configuration:

# Required
DATABASE_URL=postgresql://user:password@localhost:5432/driftos

# Drift Thresholds (tuned defaults)
DRIFT_STAY_THRESHOLD=0.38        # Above = same topic
DRIFT_NEW_CLUSTER_THRESHOLD=0.15 # Below = new domain
DRIFT_ROUTE_THRESHOLD=0.42       # Above = route to existing

# Embedding Server
EMBEDDING_SERVER_URL=http://localhost:8100
EMBEDDING_MODEL=paraphrase-MiniLM-L6-v2

# Optional: LLM for fact extraction
GROQ_API_KEY=your-key
LLM_MODEL=llama-3.1-8b-instant

Database Setup

Initialize the database:

npm run db:push

Start Embedding Server

The embedding server is a Python sidecar that generates embeddings:

cd embedding-server
pip install -r requirements.txt
python server.py

The embedding server will start on port 8100.

Start the Main Server

In a new terminal:

npm run dev

Your DriftOS Embed server is now running at http://localhost:3000.

First Route

Try routing your first message:

curl -X POST http://localhost:3000/api/v1/drift/route \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv-123",
    "content": "I want to plan a trip to Japan",
    "role": "user"
  }'

Response:

{
  "action": "BRANCH",
  "driftAction": "BRANCH_NEW_CLUSTER",
  "branchId": "branch-456",
  "branchTopic": "I want to plan a trip to Japan",
  "confidence": 1.0,
  "similarity": 0,
  "isNewBranch": true
}

Tuning Thresholds

The default thresholds work well for general conversation, but you may need to adjust for your use case:

# Conservative (fewer branches)
DRIFT_STAY_THRESHOLD=0.30

# Aggressive (more branches)
DRIFT_STAY_THRESHOLD=0.45

Next Steps

Learn about threshold tuning
Explore the API endpoints
Use the JavaScript SDK for easier integration

Getting Started

On this page