Skip to content

Active Graph KG Documentation

Welcome to the Active Graph KG documentation — a production-ready knowledge graph system with semantic search, LLM-powered Q&A, and self-improving capabilities.

Quick Navigation

What is Active Graph KG?

Active Graph KG is a self-improving knowledge graph that combines:

  • Semantic Search - pgvector-powered vector search with hybrid ranking
  • LLM Q&A - Citation-backed answers using retrieval-augmented generation
  • Self-Improving - Automatic drift detection, scheduled refreshes, and trigger-based updates
  • Multi-Tenant - Row-level security (RLS) with per-tenant isolation
  • Production-Ready - JWT auth, rate limiting, Prometheus metrics, comprehensive testing

Key Features

✅ 24 REST API endpoints - Health, nodes, edges, search, ask, triggers, events, admin
✅ Hybrid search - Vector + text search with RRF (Reciprocal Rank Fusion) reranking
✅ Strict citations - LLM answers cite source nodes with [0], [1], [2] references
✅ Triggers & patterns - Auto-refresh nodes on conditions, schedule-based updates
✅ Row-Level Security - PostgreSQL RLS policies for tenant isolation
✅ Comprehensive testing - 50+ tests covering unit, integration, E2E, security
✅ Observability - Prometheus metrics, Grafana dashboards, debug endpoints

Getting Started

1. Quick Setup (5 minutes)

# Clone and setup
git clone https://github.com/puneetrinity/active-graph-kg.git
cd active-graph-kg
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Initialize database
export ACTIVEKG_DSN="postgresql://user:pass@localhost:5432/activekg"
psql $ACTIVEKG_DSN -f db/init.sql
psql $ACTIVEKG_DSN -f enable_rls_policies.sql

# Start API server
export GROQ_API_KEY="your-key-here"
uvicorn activekg.api.main:app --host 0.0.0.0 --port 8000

See the setup instructions above for detailed configuration options.

2. Create Your First Node

curl -X POST http://localhost:8000/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "id": "python-guide",
    "classes": ["Document"],
    "props": {
      "title": "Python Best Practices",
      "text": "Use type hints for better code clarity. Follow PEP 8 style guide."
    }
  }'

3. Ask a Question

curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are Python best practices?"
  }'

Response: 

{
  "answer": "Python best practices include using type hints for better code clarity and following the PEP 8 style guide [0].",
  "sources": [
    {
      "node_id": "python-guide",
      "title": "Python Best Practices",
      "similarity": 0.92
    }
  ]
}

Operations Guides

Production deployment, security, and monitoring documentation.

Development Guides

Documentation for developers working with the codebase.

  • API Reference - All 24 endpoints with authentication, examples, error codes
  • Testing Guide - Setup, test execution, results, troubleshooting
  • Architecture - System components, data flow, code locations

Additional Resources

  • Phase 1+ Summary - Executive summary with architecture overview
  • Phase 1+ Improvements - Detailed implementation guide
  • Production Optimization Guide - 7-phase optimization plan
  • Implementation Status - Complete feature inventory with code locations

See the repository root for these additional documents.

Support & Community

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                         FastAPI REST API                     │
│  /health /nodes /search /ask /triggers /events /admin /_prom │
└────────────┬────────────────────────────────────────────────┘
             │
┌────────────▼────────────────────────────────────────────────┐
│                      Graph Repository                        │
│  • Nodes & Edges CRUD    • Vector Search    • Hybrid Search │
│  • Triggers & Patterns   • Events & Lineage • RLS Isolation │
└────────────┬────────────────────────────────────────────────┘
             │
┌────────────▼────────────────────────────────────────────────┐
│                  PostgreSQL + pgvector + RLS                 │
│  • Nodes (JSONB + vector)  • Edges  • Events  • Triggers    │
│  • Row-Level Security (tenant_id)   • Full-text search      │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                   Background Scheduler                        │
│  • Trigger polling   • Scheduled refreshes   • Drift monitor │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                   LLM Provider (Groq/OpenAI)                  │
│  • Citation-backed answers   • Intent detection   • Embeddings│
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                   Redis (Rate Limits & Cache)                 │
│  • Per-tenant rate limiting   • /ask response cache          │
└──────────────────────────────────────────────────────────────┘

See Architecture Guide for detailed component documentation.

License

This project is licensed under the MIT License - see the LICENSE file for details.

For commercial use and enterprise support, see LICENSE-ENTERPRISE.md.

Last Updated: 2025-11-24
Documentation Version: 1.0.0