llm-gateway/packages/lightrag-sidecar/GETTING_STARTED.md

# Getting Started — LightRAG Sidecar

Quick start guide to test and deploy the hybrid knowledge graph sidecar.

## Prerequisites (5 min)

Ensure these are running on your machine:

```bash
# PostgreSQL
psql --version
psql -l  # should show databases

# Qdrant vector database
curl http://localhost:6333/health

# Ollama LLM
curl http://192.168.178.213:11434/api/tags | grep qwen2.5:14b
```

**Don't have them?** See [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md) for installation.

## Step 1: Verify Local Setup (2 min)

```bash
cd packages/lightrag-sidecar
bash scripts/verify_local_setup.sh
```

✅ Should show all checks passing. If not, fix the warnings/errors listed.

## Step 2: Initialize Database (1 min)

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Initialize database
python scripts/init_db.py
```

**Expected output**: `✓ Tables created: entities, relations, documents, query_logs, evaluation_results`

## Step 3: Start Local Sidecar (1 min)

```bash
# Terminal 1: Run sidecar
uvicorn app.main:app --host 0.0.0.0 --port 3140 --reload
```

**Expected output**: `INFO: Uvicorn running on http://0.0.0.0:3140`

## Step 4: Test Endpoints (5 min)

In another terminal:

```bash
# Terminal 2: Test health
curl http://localhost:3140/api/kg/health

# Test ingestion (single document)
curl -X POST http://localhost:3140/api/kg/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "transceiver",
    "documents": [{
      "title": "400G Guide",
      "content": "400G transceivers use PAM4 modulation for 400 gigabit speeds.",
      "source": "test"
    }]
  }'

# Test query
curl -X POST http://localhost:3140/api/kg/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is 400G?",
    "domain": "transceiver",
    "top_k": 5
  }'
```

**Expected responses**: 
- Health: `{"status": "healthy", ...}`
- Ingestion: `{"job_id": "...", "status": "queued", ...}`
- Query: `{"results": [...], "latency_ms": ...}`

## Step 5: Run Full Test Workflow (20 min)

Follow the complete testing guide:

```bash
# Read the testing guide
cat TESTING.md

# Run phases 1-5 as documented
# Phase 1: Health check ✓ (done above)
# Phase 2: Document ingestion (do above)
# Phase 3: Query testing (do above)
# Phase 4: Entity verification
# Phase 5: Evaluation metrics
```

**Success criteria**:
- ✅ No ERROR logs
- ✅ Queries return results
- ✅ Latency <500ms
- ✅ Entity extraction works

## Step 6: Populate Evaluation Dataset (10 min)

Once documents are in the system:

```bash
# Terminal 2: Interactive evaluation set population
python scripts/populate_eval_set.py
```

For each query, the script shows suggested documents. You verify with `y/n/edit`.

**Output**: Updated `data/eval-transceiver-50qa.json` with ground truth document IDs.

## Ready for Erik Deployment? (30 min)

If all tests pass:

1. ✅ Health check passes
2. ✅ Documents ingested
3. ✅ Queries return results
4. ✅ Evaluation dataset populated
5. ✅ No error logs

**Next**: Follow [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md) for Erik deployment.

## Troubleshooting

### Cannot connect to PostgreSQL
```bash
# Start PostgreSQL
brew services start postgresql@15

# Or check if running
ps aux | grep postgres
```

### Qdrant not responding
```bash
# Start Qdrant
docker run -p 6333:6333 qdrant/qdrant:latest
```

### Ollama timeouts
```bash
# Verify model is loaded
ollama list

# Or load it
ollama pull qwen2.5:14b
```

### "Port 3140 already in use"
```bash
# Kill existing process
lsof -ti:3140 | xargs kill -9

# Or use different port
uvicorn app.main:app --port 3141
```

## Files of Interest

| File | Purpose |
|------|---------|
| `README.md` | Architecture overview |
| `IMPLEMENTATION.md` | Component details |
| `TESTING.md` | Complete testing guide (5 phases) |
| `DEPLOYMENT_CHECKLIST.md` | Erik deployment steps |
| `READINESS_CHECKLIST.md` | Pre-deployment verification |
| `PHASE_2_DELIVERY.md` | What was delivered |

## Quick Command Reference

```bash
# Start sidecar
uvicorn app.main:app --reload

# Test health
curl http://localhost:3140/api/kg/health

# Ingest documents
curl -X POST http://localhost:3140/api/kg/ingest \
  -H "Content-Type: application/json" \
  -d '{"domain": "transceiver", "documents": [...]}'

# Query
curl -X POST http://localhost:3140/api/kg/query \
  -H "Content-Type: application/json" \
  -d '{"query": "...", "domain": "transceiver"}'

# Evaluate
curl -X POST http://localhost:3140/api/kg/eval \
  -H "Content-Type: application/json" \
  -d '{"domain": "transceiver", "queries": [...]}'

# Check database
psql -U tip_kg -d tip_lightrag -c "SELECT COUNT(*) FROM documents;"
```

## Expected Timeline

| Step | Time | Status |
|------|------|--------|
| Verify setup | 2 min | ⚙️ |
| Initialize DB | 1 min | ⚙️ |
| Start sidecar | 1 min | ⚙️ |
| Test endpoints | 5 min | ⚙️ |
| Full test workflow | 20 min | 📋 |
| Populate eval set | 10 min | 📋 |
| **Total** | **~40 min** | ✅ Ready |

---

**Next**: Once complete, proceed to [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md) for Erik production deployment.

**Questions?** See [TESTING.md](./TESTING.md) for detailed troubleshooting.