Graph RAG Orchestrator =================================
Graph RAG Orchestrator
=================================
Lightweight, reusable workflow runner and service for Agentic RAG. Ships with:
- YAML/JSON workflow DSL
- Durable executions/steps in Postgres
- BullMQ queues per node type (Redis)
- Wait/resume tokens
- Minimal Fastify HTTP API
- Hooks for LangChain, Pinecone, LangSmith
- Minimal Admin UI for executions/steps
- JS/TS & Python SDKs for integrations
- React embedding components for workflow launch/status
- Webhook signature utilities
Quick Start
-----------
1) Docker Compose
``
docker compose up --build
API at http://localhost:8080, Admin at http://localhost:5173.
2) Local Dev
- Copy .env.example to .env and fill valuesENCRYPTION_MASTER_KEY
- Set (32+ chars / base64) for tenant data encryptionnpm i -g pnpm@9 && pnpm i
- Install:
- Run service:
- Run admin:
SDKs & Embedding
-----------------
- JavaScript/TypeScript SDK (@plexity/sdk): see docs/sdk-js.md
- Python SDK (): see docs/sdk-python.md
- React components () for UI embedding: see docs/react-components.md
- Webhook validation helpers included in both SDKs
Run pnpm sandbox:seed to provision a local org + credentials. Full sandbox instructions live in docs/sandbox.md.
GraphRAG endpoints require a real organization row. The core multi-tenancy migration (migrations/010_multi_tenancy.sql) inserts a slug='default' org the first time it runs. If you are pointing at a fresh database make sure those SQL migrations have been applied before hitting /graphrag/**, or set GRAPHRAG_DEFAULT_ORG_ID/DEFAULT_ORG_ID in your environment to a known org id.
Migrations
----------
Run the SQL in migrations/001_init.sql against your Postgres instance.
GraphRAG routes require an organization row. The multi-tenancy migration (migrations/010_multi_tenancy.sql) creates a slug='default' org if one is missing; make sure that migration has been applied or set GRAPHRAG_DEFAULT_ORG_ID/DEFAULT_ORG_ID in your environment before exercising /graphrag/** endpoints.
Prisma mirrors the SQL schema (prisma/schema.prisma). When pointing at an existing database run pnpm prisma migrate resolve --applied 000_baseline once to mark the baseline, then pnpm prisma generate for typed access.
Prisma now mirrors the same schema under prisma/schema.prisma. Point the CLI at your database and run pnpm prisma migrate resolve --applied 000_baseline once to mark the baseline, then pnpm prisma generate for typed access.
Plexity GraphRAG Pipeline
-------------------------
- Next.js API surface lives under apps/web with routes for document events, retrieval, and admin recompute triggers.packages/core
- Shared ingestion utilities are published from (chunking, embeddings, Neo4j helpers, ranking, cache keys).apps/worker
- Queue workers, graph analytics, summarisation, cleanup, and tenant-scoped rebuild jobs run from (BullMQ + node-cron).infra/docker-compose.yml
- Local infrastructure helpers (Redis + Neo4j) sit in ; copy .env.example and fill the Plexity-specific envs (EMBED_MODEL, ADMIN_BEARER_TOKEN, etc.).pnpm --filter @plexity/web dev
- Start the stack with and pnpm --filter @plexity/worker dev once dependencies are installed (pnpm i).
Production Setup
----------------
1. Provision infrastructure (Redis + Neo4j). For local testing, docker compose -f infra/docker-compose.yml up -d will bring up both services.cypher-shell -u "$NEO4J_USER" -p "$NEO4J_PASS" -a "$NEO4J_URI" --file infra/neo4j/schema.cypher
2. Apply the graph schema + vector index: . Override EMBED_DIM during the call if your embedding model differs from 3072 dimensions.OPENAI_API_KEY
3. Ensure required env vars are set (, EMBED_MODEL, EMBED_DIM, REDIS_URL, NEO4J_URI, NEO4J_USER, NEO4J_PASS, ADMIN_BEARER_TOKEN). See .env.example for defaults.pnpm --filter @plexity/web dev
4. Start the API surface: (or next start after next build for production).pnpm --filter @plexity/worker dev
5. Start the worker processes independently: (or compile and run with Node in production). This boots BullMQ consumers and schedules hourly/daily jobs.POST /api/events/document
6. Drive ingestion via and retrieval via POST /api/query. The admin endpoint /api/admin/recompute can enqueue maintenance jobs when invoked with the bearer token (jobs: hourly, summaries, cleanup)./api/admin/recompute
7. For tenant-scoped rebuilds after major entity/matching changes, call with { "job": "rebuild", "tenantId": ". The worker runs a targeted similarity refresh instead of reprocessing all customers.
API
---
- POST /executions → { id, status }
- GET → list executions/executions/:id
- GET → execution row/executions/:id/steps
- GET → steps for an execution/resume/:token
- POST → resume a paused step/health
- GET → service health
Tenant Portal
-------------
- POST /orgs → self-service tenant registration; returns owner membership + seed JWT.POST /auth/login
- → exchange org slug + credentials for tenant-scoped JWT.GET /orgs/me
- → organization metadata, quota snapshot, membership context.PATCH /orgs/me/branding
- , PATCH /orgs/me/portal-settings → configure portal theming + support links.GET /orgs/me/members
- , POST /orgs/me/members/invite, PATCH /orgs/me/members/:id → membership lifecycle.GET|POST /api-keys
- + POST /api-keys/:id/revoke → org API keys with per-minute/burst limits.GET|POST /workflows
- , POST /workflows/:id/publish → tenant workflow management.GET /metrics
- , /stream/metrics, /events/:executionId → org-scoped telemetry feeds.
The Next.js portal UI under /portal/* (dashboard, API keys, workflows, settings) calls these endpoints directly.
Customer Readiness
------------------
- Customer Onboarding Guide
- Operations Incident Runbook
- Support SLA & Escalation Alignment
- Final Launch Rehearsal Plan
Workflows
---------
- Put YAML/JSON specs in examples or set WORKFLOWS_DIR
- Example:
Extending
---------
- Add nodes under packages/runner/src/exec/nodes/*
- Wire dependencies in
- Add more routes/UI as needed (DLQ, replayer, etc.)
License
-------
Proprietary to SprintIQ unless otherwise noted.