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:

# 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 for installation.

Step 1: Verify Local Setup (2 min)

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)

# 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)

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

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

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

# 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 for Erik deployment.

Troubleshooting

Cannot connect to PostgreSQL

# Start PostgreSQL
brew services start postgresql@15

# Or check if running
ps aux | grep postgres

Qdrant not responding

# Start Qdrant
docker run -p 6333:6333 qdrant/qdrant:latest

Ollama timeouts

# Verify model is loaded
ollama list

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

"Port 3140 already in use"

# 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

# 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 for Erik production deployment.

Questions? See TESTING.md for detailed troubleshooting.