Flexible GraphRAG
Flexible GraphRAG is an open source AI context platform supporting a document processing pipeline (Docling, LlamaParse, or LiteParse), knowledge graph auto-building, ontologies, schemas, many LLM providers, GraphRAG and RAG, hybrid semantic search (fulltext, vector, property graph, RDF/SPARQL), AI query, and AI chat. The backend is Python with LlamaIndex and LangChain as peer frameworks. LlamaIndex is the default for each pipeline stage; LangChain can be selected per stage in environment configuration. The API is a REST FastAPI service. Angular, React, and Vue TypeScript frontends and an MCP server are included. The stack supports 14 data sources (10 with incremental auto-sync), 15 property graph databases, 4 RDF triple stores (Apache Jena Fuseki, Ontotext GraphDB, Oxigraph, Amazon Neptune RDF), 10 vector databases, OpenSearch / Elasticsearch / BM25 search, Alfresco, and Nuxeo. Databases and dashboards can be enabled with the provided Docker Compose layout. Optionally, the ingest pipeline, hybrid search, and AI query can run through customizable Langflow visual flows (12 custom Langflow components). As a further option, ingest can run on a CocoIndex (Rust engine) pipeline that reuses the same sources, targets, parsers and KG extractors, adding step-level memoization and automatic delete reconciliation.
New 10/19/26 — v0.8.6 release: Sign-in and permission-aware search for every repository and cloud source: Alfresco, Nuxeo, CMIS, SharePoint / OneDrive, Box, Google Drive / Cloud Storage, Azure Blob and Amazon S3, with one sign-in pill in the header whose drop-down signs you in and out of each data source and server, and a Sources picker, in the React, Vue and Angular UIs and in KG Spaces; S3 and Azure Blob results open the file through short-lived signed links; per-row Processing columns for every data source and a Deep (subfolders) checkbox; MCP permission levels and browser sign-in. See the Sign-In Guide.
New 10/17/26 — v0.8.5 release: Sign in to Alfresco in the React, Vue and Angular UIs: search and AI chat answer only from Alfresco documents you may read (with a server picker in the sign-in dialog when several Alfresco servers are in the stores), and the Alfresco source form can ingest using the sign-in. The MCP server's search and query tools filter by Alfresco permissions too (pass the user's ticket or credentials). Data-source forms no longer pre-fill credentials or get autofilled by the browser, and KG Spaces can ingest from another Alfresco server (in Other Sources, after adding alfresco to its enabledSources config; KG Spaces search still covers only the Alfresco server ACA is signed in to).
New 10/10/26 — v0.8.4 release: Hybrid search results (graph and RDF too) and AI query / AI chat answers now name the documents they came from, as links: Alfresco documents open in the Alfresco Content App viewer over their folder (or Share), Nuxeo in its Web UI, web pages and Wikipedia at their URL, and YouTube at the transcript segment's time. In KG Spaces, closing ACA's viewer returns to your search results and chat. KG Spaces hybrid search returns full results again, and ArcadeDB moves to 26.10.1.
New 10/8/26 — v0.8.3 release: The Processing tab now has per-row Search+Vector, Graphs and Auto Sync checkbox columns (Alfresco, Nuxeo and file uploads initially), so in addition to ingest, can toggle having vector+search, graphs, and auto sync, row by row, Jobs sub-tab and Run in background. KG Spaces adds Ask KG Spaces about this document / folder (then ask in AI chat). Hybrid search, AI query, and AI chat, return only from documents the signed-in Alfresco user may read.
New 10/2/26 — v0.8.2 release: The Flexible GraphRAG Angular frontend's tab components are now a shared library project, published on npm as @flexible-graphrag/angular-ui, and also used by the new KG Spaces for Alfresco Content App (kg-spaces-aca), redone as a real Apache 2.0 ACA extension. Besides using multi-select of Alfresco files and folders (any mix) from ACA's regular file list views, wherever they are, it now has the data sources tab (renamed there OTHER SOURCES) for choosing additional data sources supported by Flexible GraphRAG. AI context can be kept up to date with auto change sync from Alfresco, Nuxeo, SharePoint, Box, Amazon S3, Azure Blob Storage, Google Cloud Storage, Google Drive and OneDrive, and ingested without auto sync from File Upload, CMIS, Web Pages, Wikipedia and YouTube.
New 9/16/26 — v0.8.1 release: Alfresco Docker stack upgraded to Community 26.2.0, support for Alfresco OpenSearch and Elasticsearch (shared with the Flexible GraphRAG app or dedicated), and a file upload data source path-traversal fix.
New 8/18/26 — v0.8.0 release: Optional CocoIndex integration — Rust-backed CocoIndex pipeline mixed with Flexible GraphRAG sources (incl. detectors), functions, and targets (more PG/vector/RDF/search); same UI/REST/MCP. Standalone app.py also supported. Now with custom KG extractors (bring your own, or fall back to the built-in one per document) and entity resolution. New meeting-notes example (examples/cocoindex/meeting_notes_graph_any/) — a CocoIndex example ported to run against any configured graph store and source. See CocoIndex Integration.
New 8/8/26 — v0.7.2 release: Nuxeo added as a data source — all 3 UIs (React/Vue/Angular) plus REST/MCP, with basic / token / OAuth2 auth and real-time incremental sync via the Nuxeo audit event stream (Kafka). Alfresco OAuth2 and ticket authentication added across the source, all 3 UIs, initial ingest, and real-time sync. Alfresco Community 26.1 Docker upgrade. The MCP server gained optional OAuth2 on its transport (bearer token via your IdP) and moved to FastMCP 3. Requires python-alfresco-api >= 1.2.1.
New 7/20/26 — v0.7.1 release: Document processing now supports LiteParse in addition to the previous Docling and LlamaParse support. Langflow integration ships with fixes and an optional Langflow Docker image bundling the 12 "Flexible" components. MS Graph delta query support was added for more efficient incremental updating with SharePoint and OneDrive data sources.
New 7/5/26: Optional Langflow visual flows — the app can run its ingest pipeline, hybrid search, and AI query through customizable Langflow flows (12 custom Flexible GraphRAG components), using your existing .env config. See Langflow Integration.
New 5/6/26: 15 property graph databases total: 8 supported on both LlamaIndex and LangChain, 1 LI-only (Google Cloud Spanner Graph), 6 LC-only (ArangoDB, Apache AGE, Azure Cosmos DB for Gremlin, Apache HugeGraph, SurrealDB, TigerGraph). AWS Neptune RDF/SPARQL added. All 10 vector databases, all 3 search engines, and all LLM/embedding providers work with both LlamaIndex and LangChain. Every pipeline stage (chunking, KG extraction, graph write, vector write, search write, and retrieval fusion) can be configured independently. (Data source reading is LlamaIndex only; RDF stores use framework-independent adapters with LangChain Text-to-SPARQL retrieval.)
New: Flexible GraphRAG now supports RDF-based ontologies for both property graph databases and RDF triple store databases (Graphwise Ontotext GraphDB, Fuseki, and Oxigraph). Document ingestion with KG extraction, auto incremental data source change detection, and UI search (hybrid search, AI query, and AI chat) are all supported with both database types.
New: Flexible GraphRAG supports automatic incremental updates (Optional) from most data sources, keeping your Vector, Search and Graph databases synchronized in real-time or near real-time.
New: KG Spaces Integration of Flexible GraphRAG in Alfresco ACA Client
New in v0.6.0: Version 0.6.0 broadened framework and database choice: LangChain is a full peer to LlamaIndex (per-stage env pickers for chunking, vector, search, property graph, KG extraction, fusion). 15 property graph backends: 8 on both frameworks, Google Cloud Spanner (LlamaIndex-only), 6 LangChain-only (ArangoDB, Apache AGE, Azure Cosmos DB for Gremlin, HugeGraph, SurrealDB, TigerGraph). RDF includes Apache Jena Fuseki, Ontotext GraphDB, Oxigraph, and Amazon Neptune RDF. Incremental delete, LangChain adapters, and cleanup paths were extended across stores.
Features
- Hybrid Search: Configurable hybrid search combining vector search, full-text search, property-graph GraphRAG, and SPARQL against RDF stores.
- Knowledge Graph GraphRAG: Extracts entities and relationships from documents to build graphs in property graph databases and RDF stores. Optional schemas and ontologies guide extraction or act as a starting point for the LLM to extend.
- RDF/Ontology Support: Load OWL/RDFS ontologies to guide KG extraction into any property graph or RDF store; SPARQL 1.1 queries; RDF 1.2 triple annotations; full UI pipeline (ingest, hybrid search, AI query/chat, incremental auto-sync). See Ontology and RDF Support below.
- 15 Property Graph Databases: 8 on both LI+LC (Neo4j, ArcadeDB, FalkorDB, Ladybug, Memgraph, NebulaGraph, Amazon Neptune, Neptune Analytics), 1 LI-only (Google Cloud Spanner), 6 LC-only (ArangoDB, Apache AGE, Cosmos Gremlin, HugeGraph, SurrealDB, TigerGraph) — with KG extraction, hybrid search, and AI query/chat
- 4 RDF Triple Stores: Apache Jena Fuseki, Ontotext GraphDB, Oxigraph, Amazon Neptune RDF.
- 10 Vector Databases: Qdrant, Elasticsearch, OpenSearch, Neo4j, Chroma, Milvus, Weaviate, Pinecone, PostgreSQL pgvector, LanceDB — for semantic similarity search
- 3 Search Databases: Elasticsearch, OpenSearch, BM25 (built-in) — for full-text search and hybrid ranking
- LLM providers (KG extraction & chat): Ollama, OpenAI, Azure OpenAI, Google Gemini, Anthropic Claude, Google Vertex AI, Amazon Bedrock, Groq, Fireworks AI, OpenAI-compatible endpoints (
openai_like), OpenRouter, LiteLLM proxy, and vLLM — configurable viaLLM_PROVIDER; see Supported LLM Providers - Embedding providers: OpenAI, Ollama, Azure OpenAI, Google GenAI, Vertex AI, Bedrock, Fireworks, OpenAI-like (
EMBEDDING_KIND=openai_like), and LiteLLM — see LLM Configuration - Dual-framework pipeline: LlamaIndex and LangChain are first-class choices for chunking, vector and search adapters, property graphs, KG extraction, RDF text-to-SPARQL retrieval, and hybrid fusion—each stage can be set independently (LlamaIndex defaults). See Framework Configuration.
- Document Processing: Docling (default), LlamaParse (cloud API), or LiteParse (local, lightweight) document parsing.
- : 10 with incremental auto sync (Alfresco, Nuxeo, SharePoint, OneDrive, Box, Google Drive, Amazon S3, Google Cloud Storage, Azure Blob Storage, Filesystem) and 4 without (CMIS, Web Pages, Wikipedia, YouTube).
Frontend Screenshots
Angular Frontend - Tabbed Interface
| Sources Tab | Processing Tab | Search Tab | Chat Tab |
|---|---|---|---|
 |  |  |  |
React Frontend - Tabbed Interface
| Sources Tab | Processing Tab | Search Tab | Chat Tab |
|---|---|---|---|
 |  |  |  |
| Sources Tab | Processing Tab | Search Tab | Chat Tab |
|---|---|---|---|
 |  |  |  |
Vue Frontend - Tabbed Interface
| Sources Tab | Processing Tab | Search Tab | Chat Tab |
|---|---|---|---|
 |  |  |  |
System Components
FastAPI Backend (/flexible-graphrag)
- REST API Server: Provides endpoints for document ingestion, search, and AI query/chat
- Hybrid Search Engine: Combines vector similarity (RAG), fulltext (BM25), and graph traversal (GraphRAG)
- Document Processing: Advanced document conversion with Docling, LlamaParse, and LiteParse integration
- Configurable Architecture: Environment-based configuration for all components
- Async Processing: Background task processing with real-time progress updates
MCP Server (/flexible-graphrag-mcp)
- MCP Client support: Model Context Protocol server for Claude Desktop and other MCP clients
- Full API Parity: Tools like
ingest_documents()support all 14 data sources with source-specific configs: filesystem, repositories (Alfresco, SharePoint, Box, CMIS, Nuxeo), cloud storage, web;skip_graphflag for all data sources;pathsparameter for filesystem/Alfresco/CMIS; Alfresco also supportsnodeDetailslist (multi-select for KG Spaces) - Additional Tools:
search_documents(),query_documents(),ingest_text(), system diagnostics, and health checks - Dual Transport: HTTP mode for debugging, stdio mode for production
- Tool Suite: 12 tools for document processing, search, sign-in and system management (14 with
MCP_BROWSER_SIGN_IN=true); search and query can be permission-filtered per user (three levels) - Multiple Installation: pipx system installation or uvx no-install execution
UI Clients (/flexible-graphrag-ui)
- Angular Frontend: Material Design with TypeScript
- React Frontend: Modern React with Vite and TypeScript
- Vue Frontend: Vue 3 Composition API with Vuetify and TypeScript
- Unified Features: All clients support the 4 tab views, async processing, progress tracking, and cancellation
Docker Infrastructure (/docker)
- Modular Database Selection: Include/exclude vector, graph, and search engines, and Alfresco with single-line comments
- Flexible Deployment: Hybrid mode (databases in Docker, apps standalone) or full containerization
- NGINX Reverse Proxy: Unified access to all services with proper routing
- Built-in Database Dashboards: Most server dockers also provide built-in web interface dashboards (Neo4j browser, ArcadeDB, FalkorDB, OpenSearch, etc.)
- Separate Dashboards: Additional dashboard dockers are provided: including Kibana for Elasticsearch and optional Ladybug Explorer (see
docker/includes/ladybug-explorer.yaml).
Data Sources
Flexible GraphRAG supports 14 different data sources for ingesting documents into your knowledge base (Nuxeo missing from older screenshots):
File & Upload Sources
- File Upload - Direct file upload through web interface with drag & drop support
Cloud Storage Sources
- Amazon S3 - AWS S3 bucket integration
- Google Cloud Storage (GCS) - Google Cloud storage buckets
- Azure Blob Storage - Microsoft Azure blob containers
- OneDrive - Microsoft OneDrive personal/business storage
- Google Drive - Google Drive file storage
Enterprise Repository Sources
- Alfresco - Alfresco ECM/content repository with two integration options:
- KG Spaces ACA Extension - Integrates the Flexible GraphRAG Angular UI as an extension plugin within the Alfresco Content Application (ACA), enabling multi-select document/folder ingestion with nodeIds directly from the Alfresco interface. Its title bar has a sign-in pill for the other sources and servers (Angular lib option
searchSignIn), so KG Spaces search and chat can also use other sources' documents the user may read - Flexible GraphRAG Alfresco Data Source - Direct integration using Alfresco paths (e.g., /Shared/GraphRAG, /Company Home/Shared/GraphRAG, or /Shared/GraphRAG/cmispress.txt)
- KG Spaces ACA Extension - Integrates the Flexible GraphRAG Angular UI as an extension plugin within the Alfresco Content Application (ACA), enabling multi-select document/folder ingestion with nodeIds directly from the Alfresco interface. Its title bar has a sign-in pill for the other sources and servers (Angular lib option
- Nuxeo - Nuxeo content repository (File and Note documents); basic / token (X-Authentication-Token) / OAuth2 auth, path or node selection, and real-time incremental sync via the Nuxeo audit event stream (Kafka)
- SharePoint - Microsoft SharePoint document libraries
- Box - Box.com cloud storage
- CMIS (Content Management Interoperability Services) - Industry-standard content repository interface
Web Sources
- Web Pages - Extract content from web URLs
- Wikipedia - Ingest Wikipedia articles by title or URL
- YouTube - Process YouTube video transcripts
Each data source includes:
- Configuration Forms: Easy-to-use interfaces for credentials and settings
- Progress Tracking: Real-time per-file progress indicators
- Flexible Authentication: Support for various auth methods (API keys, OAuth, service accounts)
- Per-user sign-in (Alfresco, Nuxeo, CMIS, SharePoint, OneDrive, Box, Google Drive, GCS, Azure Blob, S3): search and chat answer only from documents the signed-in user may read. See Sign-In and Permission-Aware Search
Incremental Updates & Auto-Sync
NEW! Flexible GraphRAG supports automatic incremental updates (Optional) from most data sources, keeping your Vector, Search and Graph databases synchronized in real-time or near real-time:
Features:
- Modification Date Tracking: Uses file modification timestamps (ordinal) to detect changes
- Content Hash Optimization: Skips reprocessing when file modification date changed but content hasn't
- Dual Mechanism: Event-driven streams (real-time) + periodic polling fallback
- LlamaIndex Integration: Uses proper abstractions for all databases
- UI, REST API, MCP Server: Setting up an auto update data source location can be done thru the 3 UIs, with the REST API, or with the MCP server
Setup Requirements:
Enable incremental updates in your .env file:
ENABLE_INCREMENTAL_UPDATES=true
# PostgreSQL database for state management
# By default, uses the pgvector database from docker-compose.yaml
POSTGRES_INCREMENTAL_URL=postgresql://postgres:password@localhost:5433/postgres
Note: The incremental updates system uses PostgreSQL to track document state. The docker-compose.yaml includes a pgvector container that can be used both as a vector database option and for incremental updates state management. The database connection creates the necessary tables automatically on first use.
Usage:
- Tick the Auto Sync column for the row(s) in the Processing tab (with the incremental registry on, every data source has per-row Search+Vector / Graphs / Auto Sync columns; the older "Enable auto change sync" checkbox appears only when the registry is off)
- Deep on the Alfresco, Nuxeo and Box forms includes subfolders (recursive) in the ingest and its auto sync
- For S3: Also provide the "SQS Queue URL" for event notifications
- For GCS: Also provide the "Pub/Sub Subscription Name" for real-time updates
PostgreSQL for State Management:
The docker/includes/postgres-pgvector.yaml sets up two databases automatically on first start: flexible_graphrag (for optional pgvector vector storage) and flexible_graphrag_incremental (for incremental update state management, with its schema created automatically). pgAdmin is also configured at http://localhost:5050 with both databases pre-registered — just enter the master password admin when prompted, then use password for the server connection and save it. See docs/DATABASES/POSTGRES-SETUP.md for details.
Documentation:
- System overview:
docs/DATA-SOURCES/INCREMENTAL-UPDATE-AUTO-SYNC/README.md - Quick start:
docs/DATA-SOURCES/INCREMENTAL-UPDATE-AUTO-SYNC/QUICKSTART.md - Detailed setup:
docs/DATA-SOURCES/INCREMENTAL-UPDATE-AUTO-SYNC/SETUP-GUIDE.md - API reference:
docs/DATA-SOURCES/INCREMENTAL-UPDATE-AUTO-SYNC/API-REFERENCE.md - PostgreSQL setup:
docs/DATABASES/POSTGRES-SETUP.md
Scripts:
scripts/incremental/sync-now.sh|.ps1|.bat- Trigger immediate synchronizationscripts/incremental/set-refresh-interval.sh|.ps1|.bat- Configure polling intervalscripts/incremental/TIMING-CONFIGURATION.md- Timing configuration detailsscripts/incremental/README.md- Script usage documentation
Document Processing Options
All data sources support three document parser options (full per-parser format matrix in Supported File Formats):
Docling (Default):
- Open-source, local processing
- Free with no API costs
- GPU acceleration supported (CUDA/Apple Silicon) for 5-10x faster processing
- Built-in OCR for scanned documents and images —
DOCLING_OCR=true+DOCLING_OCR_ENGINE=auto|rapidocr|easyocr|tesseract_cli|tesserocr|ocrmac - Multi-language support (English, German, French, Spanish, Czech, Russian, Chinese, Japanese, etc.)
- Configured via:
DOCUMENT_PARSER=docling DOCLING_DEVICE=auto|cpu|cuda|mps— control GPU vs CPU processingSAVE_PARSING_OUTPUT=true— save intermediate parsing results for inspection (works for all three parsers)PARSER_FORMAT_FOR_EXTRACTION=auto|markdown|plaintext— control format used for knowledge graph extraction- See Docling GPU + OCR Configuration Guide for setup details | Quick Reference
LlamaParse:
- Cloud-based API service with advanced AI
- Multimodal parsing with Claude Sonnet 3.5
- Three modes available:
parse_page_without_llm- 1 credit/pageparse_page_with_llm- 3 credits/page (default)parse_page_with_agent- 10-90 credits/page
- Configured via:
DOCUMENT_PARSER=llamaparse+LLAMAPARSE_API_KEY - Get your API key from LlamaCloud
- New:
SAVE_PARSING_OUTPUT=true- Save parsed output and metadata for inspection - New:
PARSER_FORMAT_FOR_EXTRACTION=auto|markdown|plaintext- Control format used for knowledge graph extraction
LiteParse:
- Open-source, local processing (Rust/PyO3) — free, no API key
- Natively parses PDFs with bundled Tesseract OCR;
.txt/.mdread directly - Office formats need LibreOffice, images need ImageMagick — see Supported File Formats
- Optional complexity-based routing of scanned/complex docs to Docling or LlamaParse via
LITEPARSE_COMPLEX_ROUTING - Configured via:
DOCUMENT_PARSER=liteparse; installuv pip install liteparse - Supports
SAVE_PARSING_OUTPUTandPARSER_FORMAT_FOR_EXTRACTIONlike the other parsers
Supported File Formats
Flexible GraphRAG processes documents, images, and audio across its three parsers:
- Documents: PDF (
.pdf); Microsoft Office + legacy (.docx/.xlsx/.pptx,.doc/.xls/.ppt); web (.html/.htm/.xhtml); data (.csv/.tsv/.json/.xml); documentation (.md/.markdown/.asciidoc/.rtf/.txt/.epub) - Images:
.png/.jpg/.jpeg/.gif/.bmp/.webp/.tiff/.tif - Audio:
.wav/.mp3/.mp4/.m4a(speech recognition / transcription)
Capabilities vary by parser — Docling and LlamaParse handle all of the above natively (advanced layout/table/formula analysis, configurable OCR, VLM/multimodal, ASR); LiteParse parses PDFs natively and needs LibreOffice for Office formats / ImageMagick for images. Both markdown and plaintext are saved, and the best is auto-selected for knowledge-graph extraction, embeddings, and search (markdown for tables, plaintext for text-heavy docs; override with PARSER_FORMAT_FOR_EXTRACTION).
Full per-parser matrix, OCR/VLM options, and output formats: Supported File Formats.
Database Configuration
Flexible GraphRAG uses three types of databases for its hybrid search capabilities. Each can be configured independently via environment variables.
Search Databases (Full-Text Search)
Set SEARCH_DB to select the store and SEARCH_BACKEND=llamaindex or langchain for the framework.
-
BM25 (Built-in): Local in-memory BM25 full-text search with TF-IDF ranking
- Dashboard: None (file-based)
- Configuration:
SEARCH_DB=bm25 BM25_SEARCH_DB_CONFIG={"persist_dir": "./bm25_index"}
-
Elasticsearch: Enterprise search engine with advanced analyzers, faceted search, and real-time analytics
- Dashboard: Kibana (http://localhost:5601)
- Configuration:
SEARCH_DB=elasticsearch ELASTICSEARCH_SEARCH_DB_CONFIG={"hosts": ["http://localhost:9200"], "index_name": "hybrid_search"}
-
OpenSearch: AWS-led open-source fork with native hybrid scoring (vector + BM25) and k-NN algorithms
- Dashboard: OpenSearch Dashboards (http://localhost:5601)
- Configuration:
SEARCH_DB=opensearch OPENSEARCH_SEARCH_DB_CONFIG={"hosts": ["http://localhost:9201"], "index_name": "hybrid_search"}
-
None: Disable full-text search (vector search only)
- Configuration:
SEARCH_DB=none
- Configuration:
Vector Databases (Semantic Search)
Set VECTOR_DB to select the store and VECTOR_BACKEND=llamaindex or langchain for the framework.
When switching embedding models, delete existing vector indexes — dimensions differ by provider. See docs/DATABASES/VECTOR-DATABASES/VECTOR-DIMENSIONS.md for cleanup instructions.
Supported Vector Databases
-
Neo4j: Can be used as vector database with separate vector configuration
- Dashboard: Neo4j Browser (http://localhost:7474)
- Configuration:
VECTOR_DB=neo4j NEO4J_VECTOR_DB_CONFIG={"uri": "bolt://localhost:7687", "username": "neo4j", "password": "your_password", "index_name": "hybrid_search_vector"}
-
Qdrant: Dedicated vector database with advanced filtering
- Dashboard: Qdrant Web UI (http://localhost:6333/dashboard)
- Configuration:
VECTOR_DB=qdrant QDRANT_VECTOR_DB_CONFIG={"host": "localhost", "port": 6333, "collection_name": "hybrid_search"}
-
Elasticsearch: Can be used as vector database with separate vector configuration
- Dashboard: Kibana (http://localhost:5601)
- Configuration:
VECTOR_DB=elasticsearch ELASTICSEARCH_VECTOR_DB_CONFIG={"hosts": ["http://localhost:9200"], "index_name": "hybrid_search_vectors"}
-
OpenSearch: Can be used as vector database with separate vector configuration
- Dashboard: OpenSearch Dashboards (http://localhost:5601)
- Configuration:
VECTOR_DB=opensearch OPENSEARCH_VECTOR_DB_CONFIG={"hosts": ["http://localhost:9201"], "index_name": "hybrid_search_vectors"}
-
Chroma: Open-source vector database with dual deployment modes
- Dashboard: Swagger UI (http://localhost:8001/docs/) (HTTP mode)
- Configuration (Local Mode):
VECTOR_DB=chroma CHROMA_VECTOR_DB_CONFIG={"persist_directory": "./chroma_db", "collection_name": "hybrid_search"} - Configuration (HTTP Mode):
VECTOR_DB=chroma CHROMA_VECTOR_DB_CONFIG={"host": "localhost", "port": 8001, "collection_name": "hybrid_search"}
-
Milvus: Cloud-native, scalable vector database for similarity search
- Dashboard: Attu (http://localhost:3003)
RAG without GraphRAG
For faster document ingest processing (no graph extraction), and hybrid search with only full text + vector, configure:
VECTOR_DB=qdrant # Any vector store
SEARCH_DB=elasticsearch # Any search engine
PG_GRAPH_DB=none
Property Graph Databases (Knowledge Graph / GraphRAG)
Set PG_GRAPH_DB to select the store and GRAPH_BACKEND=llamaindex or langchain for the framework where both are supported. LangChain-only stores (ArangoDB, Apache AGE, HugeGraph, SurrealDB, TigerGraph, Cosmos Gremlin) route property-graph ingestion and retrieval through LangChain adapters regardless of other env defaults. LlamaIndex-only stores (Spanner): when PG_GRAPH_DB=spanner, startup forces GRAPH_BACKEND=llamaindex and ignores GRAPH_BACKEND=langchain.
-
Neo4j Property Graph: Primary knowledge graph storage with Cypher querying
- Dashboard: Neo4j Browser (http://localhost:7474)
- Configuration:
PG_GRAPH_DB=neo4j NEO4J_GRAPH_DB_CONFIG={"uri": "bolt://localhost:7687", "username": "neo4j", "password": "your_password"}
-
ArcadeDB: Multi-model database supporting graph, document, key-value, and search with SQL and Cypher
- Dashboard: ArcadeDB Studio (http://localhost:2480)
- Configuration:
PG_GRAPH_DB=arcadedb ARCADEDB_GRAPH_DB_CONFIG={"host": "localhost", "port": 2480, "username": "root", "password": "password", "database": "flexible_graphrag", "query_language": "sql"}
-
FalkorDB: High-performance graph database using GraphBLAS; purpose-built for LLM / GraphRAG
- Dashboard: FalkorDB Browser (http://localhost:3001)
- Configuration:
PG_GRAPH_DB=falkordb FALKORDB_GRAPH_DB_CONFIG={"url": "falkor://localhost:6379", "database": "falkor"}
-
Ladybug: Embedded property graph database (Cypher, single
.lbugfile) with optional structured schema and HNSW vector index on chunks; Explorer UI via Docker (port 7003)- Configuration:
PG_GRAPH_DB=ladybug LADYBUG_GRAPH_DB_CONFIG={"db_dir": "./ladybug", "db_file": "database.lbug", "use_vector_index": true, "has_structured_schema": false, "strict_schema": false}
- Configuration:
-
MemGraph: Real-time graph database with streaming support and advanced graph algorithms
- Dashboard: MemGraph Lab (http://localhost:3002)
- Configuration:
PG_GRAPH_DB=memgraph MEMGRAPH_GRAPH_DB_CONFIG={"url": "bolt://localhost:7687", "username": "", "password": ""}
-
NebulaGraph: Distributed graph database for large-scale data with horizontal scalability
- Dashboard: NebulaGraph Studio (http://localhost:7001)
- Configuration:
PG_GRAPH_DB=nebula NEBULA_GRAPH_DB_CONFIG={"space": "flexible_graphrag", "host": "localhost", "port": 9669, "username": "root", "password": "nebula"}
Ontology and RDF Support
Flexible GraphRAG supports RDF/RDFS/OWL ontologies to guide knowledge graph extraction, with optional RDF graph store backends. Ontology-guided extraction works with any configured store — property graph, RDF graph store, or both.
- Load OWL/RDFS ontologies (
owl:Class,owl:ObjectProperty,owl:DatatypeProperty,rdfs:domain,rdfs:range) to constrain entity/relation extraction; OWL is supported but not required - Works with all 15 property graph databases — no RDF store required to use ontology-guided extraction
- Full pipeline for all 4 RDF graph stores: UI document ingest → KG extraction → RDF storage; auto incremental sync; Hybrid Search and AI Query/Chat fuse RDF store results alongside vector, BM25, and property graph results
- SPARQL 1.1 queries; RDF 1.2 triple terms and relation annotations (
{| |}syntax); XSD-typed literals from OWLDatatypePropertyranges
RDF Graph Store Configuration — set RDF_GRAPH_DB to select the store (all four support RDF 1.2 triple terms; Neptune is AWS-managed—no local compose include):
-
Apache Jena Fuseki — SPARQL 1.1 server; dashboard: http://localhost:3030
RDF_GRAPH_DB=fuseki FUSEKI_BASE_URL=http://localhost:3030 FUSEKI_DATASET=flexible-graphrag -
Ontotext GraphDB — enterprise RDF store with OWL reasoning; dashboard: http://localhost:7200
RDF_GRAPH_DB=graphdb GRAPHDB_BASE_URL=http://localhost:7200 GRAPHDB_REPOSITORY=flexible-graphrag GRAPHDB_USERNAME=admin GRAPHDB_PASSWORD=admin -
Oxigraph — lightweight local store, native RDF 1.2; dashboard: http://localhost:7878
RDF_GRAPH_DB=oxigraph OXIGRAPH_URL=http://localhost:7878 -
Amazon Neptune RDF — managed SPARQL 1.1 on Neptune (same cluster can host property graph and RDF; IAM SigV4 auth). See Neptune RDF setup.
RDF_GRAPH_DB=neptune_rdf NEPTUNE_RDF_HOST=db-neptune-1.cluster-xxxxxxxxxxxx.us-east-1.neptune.amazonaws.com NEPTUNE_RDF_PORT=8182 NEPTUNE_RDF_REGION=us-east-1 NEPTUNE_RDF_USE_IAM_AUTH=true NEPTUNE_RDF_USE_HTTPS=true # Optional explicit keys (else default AWS credential chain): # NEPTUNE_RDF_AWS_ACCESS_KEY_ID= # NEPTUNE_RDF_AWS_SECRET_ACCESS_KEY= -
None — disable RDF graph store:
RDF_GRAPH_DB=none
Docker Setup: Uncomment local RDF store includes in docker-compose.yaml (Fuseki, GraphDB, Oxigraph):
includes:
# - includes/jena-fuseki.yaml
# - includes/ontotext-graphdb.yaml
# - includes/oxigraph.yaml
Complete Documentation: docs/DATABASES/RDF/RDF-ONTOLOGY-SUPPORT.md | docs/DATABASES/RDF/RDF-STORE-USER-GUIDE.md
Framework Configuration
Every pipeline stage can independently run on LlamaIndex or LangChain via env var pickers:
LangChain-only graph stores (ArangoDB, Apache AGE, HugeGraph, SurrealDB, TigerGraph, Cosmos Gremlin) auto-select GRAPH_BACKEND=langchain. LlamaIndex-only Spanner (PG_GRAPH_DB=spanner) forces GRAPH_BACKEND=llamaindex at startup and ignores GRAPH_BACKEND=langchain (no LangChain adapter).
Complete Documentation: docs/ADVANCED/LANGCHAIN/LANGCHAIN-GRAPH-INTEGRATION.md
LLM and Embedding Configuration
Set via LLM_PROVIDER and provider-specific environment variables.
Supported LLM Providers
- OpenAI - gpt-4o-mini (default), gpt-4o, gpt-4.1-mini, gpt-5-mini, etc.
- Ollama - Local deployment (llama3.2, llama3.1, qwen2.5, gpt-oss, etc.)
- Azure OpenAI - Azure-hosted OpenAI models
- Google Gemini - gemini-2.5-flash, gemini-3-flash-preview, gemini-3.1-pro-preview, etc.
- Anthropic Claude - claude-sonnet-4-5, claude-haiku-4-5, etc.
- Google Vertex AI - Google Cloud-hosted Vertex AI Platform Gemini models
- Amazon Bedrock - Amazon Nova, Titan, Anthropic Claude, Meta Llama, Mistral AI, etc.
- Groq - Fast low-cost LPU inference, low latency: OpenAI GPT-OSS, Meta Llama (4, 3.3, 3.1), Qwen3, Kimi, etc.
- Fireworks AI - More choices, fine-tuning: Meta, Qwen, Mistral AI, DeepSeek, OpenAI GPT-OSS, Kimi, GLM, MiniMax, etc.
- OpenAI-Compatible (
openai_like) - Any OpenAI-compatible endpoint (LM Studio, LocalAI, Llamafile, vLLM, etc.) - OpenRouter - 200+ models via unified API (openai/gpt-4o-mini, anthropic/claude, meta-llama, etc.)
- LiteLLM Proxy - 100+ providers via LiteLLM proxy; sample config in
scripts/litellm_config.yaml - vLLM - High-performance local inference server (Linux/macOS; use
openai_likeon Windows)
LLM Provider Configuration
See docs/LLM/LLM-EMBEDDING-CONFIG.md for all 13 providers with detailed configuration examples.
OpenAI (recommended):
LLM_PROVIDER=openai
OPENAI_API_KEY=your_api_key
OPENAI_MODEL=gpt-4o-mini
Ollama (local):
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2:latest
Azure OpenAI:
LLM_PROVIDER=azure_openai
AZURE_OPENAI_API_KEY=your_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_ENGINE=gpt-4o-mini
Embedding Configuration
Set EMBEDDING_KIND to choose the embedding provider — independent of the LLM provider. All 13 LLM providers are also supported as embedding providers. See docs/LLM/LLM-EMBEDDING-CONFIG.md for all providers and options.
OpenAI:
EMBEDDING_KIND=openai
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=your_api_key
Ollama (local):
EMBEDDING_KIND=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_BASE_URL=http://localhost:11434
Azure OpenAI:
EMBEDDING_KIND=azure_openai
AZURE_EMBEDDING_MODEL=text-embedding-3-small
AZURE_EMBEDDING_DEPLOYMENT=your_deployment_name
AZURE_OPENAI_API_KEY=your_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
Common embedding dimensions:
- OpenAI: 1536 (text-embedding-3-small), 3072 (text-embedding-3-large)
- Ollama: 384 (all-minilm), 768 (nomic-embed-text), 1024 (mxbai-embed-large)
- Google: 768 (gemini-embedding-2-preview)
- Bedrock: 1024 (amazon.titan-embed-text-v2:0)
When switching embedding models, delete existing vector indexes. See docs/DATABASES/VECTOR-DATABASES/VECTOR-DIMENSIONS.md for cleanup instructions.
Ollama Configuration
When using Ollama, configure system-wide environment variables before starting the Ollama service:
Key requirements:
- Configure environment variables system-wide (not in Flexible GraphRAG
.envfile) OLLAMA_NUM_PARALLEL=4for optimal performance (or 1-2 if resource constrained)- Always restart Ollama service after changing environment variables
See docs/LLM/OLLAMA-CONFIGURATION.md for complete setup instructions including platform-specific steps and performance optimization.
Prerequisites
Required
- Python 3.12, 3.13, or 3.14 (as specified in
pyproject.toml) - UV package manager (for dependency management)
- Node.js 22.x (for UI clients)
- npm (package manager)
- Search database: Elasticsearch or OpenSearch
- Vector database: Qdrant (or other supported vector databases)
- Property graph database: Neo4j (or other supported property graph databases) - unless using vector-only RAG
- OpenAI with API key (recommended) or Ollama (for LLM processing)
Note: The docker/docker-compose.yaml file can provide all these databases via Docker containers.
Install
cd flexible-graphrag
uv pip install -e .
Optional (see flexible-graphrag/pyproject.toml for all options)
- LangChain 1.x integration — Optional peer stack alongside LlamaIndex (extras pin
langchain>=1.0and the LangChain 1.x line, not legacy 0.3):uv pip install -e ".[langchain]"— core LC extras: property graph stores vialangchain-communitywhere supported, 10 vector stores, 3 search stores, RDF SPARQL retrieval, native LC LLM/embedding clients for all 13 providers, KG extraction vialangchain-experimental, retrieval fusionuv pip install --override extras-overrides.txt -e ".[langchain,langchain-extras]"— adds Neo4j (LC), PostgreSQL pgvector, ArcadeDB, ArangoDB, Cosmos Gremlin, HugeGraph, TigerGraph, and related dependencies (seepyproject.tomlgrouplangchain-extras)- Apache AGE — property graph via LangChain needs the separate
age-extrasgroup (BAEM1Nlangchain-agedriver):
Runuv pip install --override extras-overrides.txt -e ".[langchain,langchain-extras,age-extras]" python scripts/patch_langchain_age.pypatch_langchain_age.pyon Python 3.14+ (required); on 3.12/3.13 it is harmless. uv pip install -e ".[spanner-extras]"— adds LI-only Spanner support viallama-index-spanner. Note:llama-index-spannerdeclaresllama-index(the meta-package) as a dependency, whichuvwill install. Uninstall it immediately after:uv pip uninstall llama-index— having bothllama-indexandllama-index-coreinstalled simultaneously can cause version conflicts, as the meta-package pins versions ofllama-index-*component packages that can clash with the versions already required by this project- SurrealDB — two-step install required (resolver conflict):
uv pip install -e ".[surrealdb-extras]" uv pip install "surrealdb>=2.0" "langchain-core>=1.3"
- ArcadeDB embedded mode (
uv pip install arcadedb-embedded>=26.3.2) — runs ArcadeDB in-process; includes a bundled JVM, no separate Java install needed; latest release: 26.3.2 - Enterprise Repositories:
- Alfresco repository - only if using Alfresco data source
- SharePoint - requires SharePoint access
- Box - requires Box Business account (3 users minimum), API keys
- CMIS-compliant repository (e.g., Alfresco) - only if using CMIS data source
Setup
🐳 Docker Deployment
Docker deployment offers multiple scenarios. Before deploying any scenario, set up your environment files:
Environment File Setup (Required for All Scenarios):
-
Backend Configuration (
.env):# Navigate to backend directory cd flexible-graphrag # Linux/macOS cp env-sample.txt .env # Windows Command Prompt copy env-sample.txt .env # Edit .env with your database credentials, API keys, and settings # Then return to project root cd .. -
Docker Configuration (
docker/.env):# Navigate to docker directory cd docker # Linux/macOS cp docker-env-sample.txt .env # Windows Command Prompt copy docker-env-sample.txt .env # Edit docker/.env for Docker-specific overrides (network addresses, service names) # Stay in docker directory for next steps
Scenario A: Databases in Docker, App Standalone (Hybrid)
Configuration Setup:
# If not already in docker directory from previous step:
# cd docker
# Edit docker-compose.yaml to uncomment/comment services as needed
# Scenario A setup in docker-compose.yaml:
# Keep these services uncommented (default setup):
- includes/neo4j.yaml
- includes/qdrant.yaml
- includes/elasticsearch-dev.yaml
- includes/kibana-simple.yaml
# Keep these services commented out:
# - includes/app-stack.yaml # Must be commented out for Scenario A
# - includes/proxy.yaml # Must be commented out for Scenario A
# - All other services remain commented unless you want a different vector database,
# graph database, OpenSearch for search, or Alfresco included
Deploy Services:
# From the docker directory
docker-compose -f docker-compose.yaml -p flexible-graphrag up -d
Scenario B: Full Stack in Docker (Complete)
Configuration Setup:
# If not already in docker directory from previous step:
# cd docker
# Edit docker-compose.yaml to uncomment/comment services as needed
# Scenario B setup in docker-compose.yaml:
# Keep these services uncommented:
- includes/neo4j.yaml
- includes/qdrant.yaml
- includes/elasticsearch-dev.yaml
- includes/kibana-simple.yaml
- includes/app-stack.yaml # Backend and UI in Docker
- includes/proxy.yaml # NGINX reverse proxy
# Keep other services commented out unless you want a different vector database,
# graph database, OpenSearch for search, or Alfresco included
Deploy Services:
# From the docker directory
docker-compose -f docker-compose.yaml -p flexible-graphrag up -d
Scenario B Service URLs:
- Angular UI: http://localhost:8070/ui/angular/
- React UI: http://localhost:8070/ui/react/
- Vue UI: http://localhost:8070/ui/vue/
- Backend API: http://localhost:8070/api/
Other Deployment Scenarios
Scenario C: Fully Standalone - Not using docker-compose at all
- Standalone backend, standalone UIs, all databases running separately
- Configure all database connections in
flexible-graphrag/.env
Scenario D: Backend/UIs in Docker, Databases External
- Using docker-compose for backend and UIs (app-stack + proxy)
- Some or all databases running separately (same docker-compose, other local Docker, cloud/remote servers)
- Configure database connections in
docker/.env: Backend in Docker reads this file- For databases in same docker-compose: Use service names (e.g.,
neo4j:7687,qdrant:6333) - For databases in other local Docker containers: Use
host.docker.internal:PORT - For remote/cloud databases: Use actual hostnames/IPs
- For databases in same docker-compose: Use service names (e.g.,
Scenario E: Mixed Docker/Standalone
- Standalone backend and UIs
- Running some databases in Docker (local) and some outside (cloud, external servers)
- Configure all database connections in
flexible-graphrag/.env: Usehost.docker.internal:PORTfor locally-running Docker databases, use actual hostnames/IPs for remote Docker or non-Docker databases
Docker Control and Configuration
Managing Docker services:
# Navigate to docker directory (if not already there)
cd docker
# Create and start services (recreates if configuration changed)
docker-compose -f docker-compose.yaml -p flexible-graphrag up -d
# Stop services (keeps containers)
docker-compose -f docker-compose.yaml -p flexible-graphrag stop
# Start stopped services
docker-compose -f docker-compose.yaml -p flexible-graphrag start
# Stop and remove services
docker-compose -f docker-compose.yaml -p flexible-graphrag down
# View logs
docker-compose -f docker-compose.yaml -p flexible-graphrag logs -f
# Restart after configuration changes
docker-compose -f docker-compose.yaml -p flexible-graphrag down
# Edit docker-compose.yaml, docker/.env, or includes/app-stack.yaml as needed
docker-compose -f docker-compose.yaml -p flexible-graphrag up -d
Configuration:
- Modular deployment: Comment/uncomment services in
docker/docker-compose.yaml - Backend configuration (Scenario B): Backend uses
flexible-graphrag/.envwithdocker/.envfor Docker-specific overrides (like using service names instead of localhost). No configuration needed inapp-stack.yaml
See docker/README.md for detailed Docker configuration.
🔧 Local Development Setup (Scenario A)
Note: Skip this entire section if using Scenario B (Full Stack in Docker).
Environment Configuration
Create environment file (cross-platform):
# Linux/macOS
cp flexible-graphrag/env-sample.txt flexible-graphrag/.env
# Windows Command Prompt
copy flexible-graphrag\env-sample.txt flexible-graphrag\.env
Edit .env with your database credentials and API keys.
Python Backend Setup (Standalone)
Option A — Install from PyPI package (Quickstart)
# 1. Create and activate a virtual environment
uv venv venv-3.13 --python 3.13
venv-3.13\Scripts\Activate # Windows
source venv-3.13/bin/activate # Linux/macOS
# 2. Install flexible-graphrag
uv pip install flexible-graphrag
# 3. Optionally install ArcadeDB embedded mode support (includes bundled JVM, no Java install needed)
uv pip install arcadedb-embedded>=26.3.2
# 3a. Optional dependency groups, for example:
uv pip install "flexible-graphrag[langchain]"
# Other extras ([langchain-extras], [age-extras], overrides): see source README, Prerequisites > Optional.
# 4. Create .env from the sample (copy from the source repo or download env-sample.txt)
copy env-sample.txt .env # Windows
cp env-sample.txt .env # Linux/macOS
# Edit .env with your LLM API keys and database settings
# 5. Start your databases (docker compose or standalone)
docker compose -f docker/docker-compose.yml up -d
# 6. Run the backend
flexible-graphrag
# or: uv run start.py
Option B — Install from source (editable)
-
Navigate to the backend directory:
cd flexible-graphrag -
Create and activate a virtual environment, then install in editable mode:
uv venv venv-3.13 --python 3.13 venv-3.13\Scripts\Activate # Windows source venv-3.13/bin/activate # Linux/macOS uv pip install -e . # see flexible-graphrag/pyproject.toml for all options # --- Optional: dependency groups from pyproject.toml [project.optional-dependencies] --- # LangChain (peer framework; use overrides when combining with langchain-extras) uv pip install -e ".[langchain]" uv pip install --override extras-overrides.txt -e ".[langchain,langchain-extras]" uv pip install --override extras-overrides.txt -e ".[langchain,langchain-extras,age-extras]" python scripts/patch_langchain_age.py uv pip install --override extras-overrides.txt -e ".[surrealdb-extras]" uv pip install "surrealdb>=2.0" "langchain-core>=1.3" uv pip install --override extras-overrides.txt -e ".[spanner-extras]" uv pip uninstall llama-index # RDF extras (base install already includes rdflib/pyoxigraph; use these if you need the named groups) uv pip install -e ".[rdf]" uv pip install -e ".[rdf-full]" # Observability uv pip install -e ".[observability]" uv pip install -e ".[observability-openlit]" uv pip install -e ".[observability-dual]" # Development tests / tooling uv pip install -e ".[dev]" # Docling OCR backends (see DOCLING_OCR in env-sample) uv pip install -e ".[docling-ocr-easyocr]" uv pip install -e ".[docling-ocr-tesserocr]" uv pip install -e ".[docling-ocr-ocrmac]" # macOS only # Embedded ArcadeDB (not a bracket extra; bundled JVM) uv pip install arcadedb-embedded>=26.3.2uv-managed venv (alternative): change
managed = falsetomanaged = trueinpyproject.toml[tool.uv]section, then just runuv pip install -e ..Notes: run only the optional lines you need. For
age-extras, runpatch_langchain_age.pyon Python 3.14+ (safe on 3.12/3.13). Forsurrealdb-extras, keep the follow-upsurrealdb/langchain-coreupgrades. Forspanner-extras,uv pip uninstall llama-indexremoves the meta-package pulled in byllama-index-spanner. See ### Optional under Prerequisites for context.Windows Note: If installation fails with "Microsoft Visual C++ 14.0 or greater is required" error, install Microsoft C++ Build Tools (required for compiling Docling dependencies). Select "Desktop development with C++" during installation.
Note: The system requires Python 3.12, 3.13, or 3.14 as specified in pyproject.toml (requires-python = ">=3.12,<3.15"). Python 3.12 and 3.13 are fully tested. Python 3.14 works with the patches applied automatically in main.py at startup. Virtual environment management is controlled by managed = false in pyproject.toml [tool.uv] section (you control venv creation and naming).
- Start the backend:
flexible-graphrag # after uv pip install flexible-graphrag # or: uv run start.py # with source
The backend will be available at http://localhost:8000.
Frontend Setup (Standalone)
Standalone backend and frontend URLs:
- Backend API: http://localhost:8000 (FastAPI server)
- Angular: http://localhost:4200 (npm start)
- React: http://localhost:5174 (npm run dev)
- Vue: http://localhost:3000 (npm run dev)
Choose one of the following frontend options to work with:
React Frontend
-
Navigate to the React frontend directory:
cd flexible-graphrag-ui/frontend-react -
Install Node.js dependencies (first time only):
npm install -
Start the development server (uses Vite):
npm run dev
The React frontend will be available at http://localhost:5174.
Angular Frontend
-
Navigate to the Angular frontend directory:
cd flexible-graphrag-ui/frontend-angular -
Install Node.js dependencies (first time only):
npm install -
Start the development server (uses Angular CLI):
npm start
The Angular frontend will be available at http://localhost:4200.
Vue Frontend
-
Navigate to the Vue frontend directory:
cd flexible-graphrag-ui/frontend-vue -
Install Node.js dependencies (first time only):
npm install -
Start the development server (uses Vite):
npm run dev
The Vue frontend will be available at http://localhost:3000.
UI Usage
The system provides a tabbed interface for document processing and querying. Follow these steps in order. See docs/UI-GUIDE/UI-GUIDE.md for full details.
1. Sources Tab
Configure your data source and select files for processing. The system supports 14 data sources:
Detailed Configuration:
File Upload Data Source
- Select: "File Upload" from the data source dropdown
- Add Files:
- Drag & Drop: Drag files directly onto the upload area
- Click to Select: Click the upload area to open file selection dialog (supports multi-select)
- Note: If you drag & drop new files after selecting via dialog, only the dragged files will be used
- Supported Formats: PDF, DOCX, XLSX, PPTX, TXT, MD, HTML, CSV, PNG, JPG, and more
- Next Step: Click "CONFIGURE PROCESSING →" to proceed to Processing tab
Alfresco Repository
- Select: "Alfresco Repository" from the data source dropdown
- Configure:
- Alfresco Base URL (e.g.,
http://localhost:8080/alfresco) - Username and password
- Path (e.g.,
/Sites/example/documentLibrary)
- Alfresco Base URL (e.g.,
- Next Step: Click "CONFIGURE PROCESSING →" to proceed to Processing tab
CMIS Repository
- Select: "CMIS Repository" from the data source dropdown
- Configure:
- CMIS Repository URL (e.g.,
http://localhost:8080/alfresco/api/-default-/public/cmis/versions/1.1/atom) - Username and password
- Folder path (e.g.,
/Sites/example/documentLibrary)
- CMIS Repository URL (e.g.,
- Next Step: Click "CONFIGURE PROCESSING →" to proceed to Processing tab
All Data Sources (13 available):
- Web Sources: Web Page, Wikipedia, YouTube
- Cloud Storage: Amazon S3, Google Cloud Storage, Azure Blob Storage, Google Drive, Microsoft OneDrive
- Enterprise Repositories: Alfresco, Microsoft SharePoint, Box, CMIS
See the Data Sources section for complete details on all 14 sources.
2. Processing Tab
Process your selected documents and monitor progress:
- Start Processing: Click "START PROCESSING" to begin document ingestion
- Monitor Progress: View real-time progress bars for each file
- Per-row columns: With the incremental registry on, every data source gets Search+Vector, Graphs and Auto Sync checkbox columns (single-folder / bucket sources get one row for the whole datasource); unticking removes from those stores, ticking re-ingests. A v0.9.0+ backend splits Graphs into Graph and RDF columns. See Tab 2 — Processing
- File Management: Click a row's ✕ to take it off the list (not from your system or the stores)
- Processing Pipeline: Documents are processed through Docling conversion, vector indexing, and knowledge graph creation
3. Search Tab
Perform searches on your processed documents. The header's sign-in pill signs you in to repositories and cloud services so results include only documents you may read, and the Sources chips limit a search to chosen sources (see Sign-In and Permission-Aware Search):
Hybrid Search
- Purpose: Find and rank the most relevant document excerpts
- Usage: Enter search terms or phrases (e.g., "machine learning algorithms", "financial projections")
- Action: Click "SEARCH" button
- Results: Ranked list of document excerpts with relevance scores and source information
- Best for: Research, fact-checking, finding specific information across documents
Q&A Query
- Purpose: Get AI-generated answers to natural language questions
- Usage: Enter natural language questions (e.g., "What are the main findings in the research papers?")
- Action: Click "ASK" button
- Results: AI-generated narrative answers that synthesize information from multiple documents
- Best for: Summarization, analysis, getting overviews of complex topics
4. Chat Tab
Interactive conversational interface for document Q&A:
- Chat Interface:
- Your Questions: Displayed on the right side vertically
- AI Answers: Displayed on the left side vertically
- Usage: Type questions and press Enter or click send
- Conversation History: All questions and answers are preserved in the chat history
- Clear History: Click "CLEAR HISTORY" button to start a new conversation
- Best for: Iterative questioning, follow-up queries, conversational document exploration
Testing Cleanup
Between tests you can clean up data:
- Run
cleanup.py: Clears vector, graph, and search indexes in one step — run from theflexible-graphragdirectory - Vector Indexes: See docs/DATABASES/VECTOR-DATABASES/VECTOR-DIMENSIONS.md for vector database cleanup instructions
- Graph Data: See docs/DATABASES/GRAPH-DATABASES/README-neo4j.md for graph-related cleanup commands
Langflow Visual Flows (Optional)
Flexible GraphRAG ships 12 custom Langflow components (implemented in Python) and four ready-made flows (ingest, search, AI query, and a combined query flow for the Langflow Playground). With ENABLE_LANGFLOW_FLOWS=true, the app runs its ingest pipeline, hybrid search, and AI query through those visual flows instead of calling the system directly — the flows execute the same backend machinery driven by your existing .env (all database, LLM/embedding, chunking, KG, RDF, and LlamaIndex/LangChain settings apply unchanged), so the pipeline becomes a flow you can customize. You can also just drag the components onto the Langflow canvas to build your own flows.
The main requirement is a separate venv for Langflow — Langflow runs the flows' Python component code in its own process, and the backend app calls the Langflow REST API to run the two flows.
1. Langflow venv — create it on any Python 3.14 except 3.14.0 (3.14.4 and 3.14.5 both work), or 3.13. Use an explicit patch version: uv venv --python 3.14.4 (or greater) — plain uv venv --python 3.14 resolves to 3.14.0, which has an OpenSSL bug that makes Langflow abort on startup. Then install Langflow and the backend (LlamaIndex + fuller LangChain), and run Langflow from the flexible-graphrag backend dir:
# --system-certs handles an SSL-inspecting corporate proxy.
# On uv < 0.11 the flag is --native-tls (newer uv deprecates that name).
uv pip install --system-certs langflow==1.11.2
uv pip install --system-certs --override extras-overrides.txt -e ".[langchain,langchain-extras]"
# (No PyJWT restore step needed: flexible-graphrag installs plain `nuxeo` +
# `authlib` + `pyjwt[crypto]`, never `nuxeo[oauth2]`, so nothing evicts PyJWT.)
# Run from the flexible-graphrag backend dir. PYTHONPATH must point at it so this repo's bundled
# `langchain` package wins over the real one (search / AI query need it):
$env:PYTHONPATH = (Get-Location).Path
langflow run --port 7860 --log-level WARNING --log-file langflow.log
Wait for Langflow to fully start — after the purple "Welcome to Langflow" box it prints Launching Langflow...; it's ready once that finishes. Then create an API key in the Langflow UI: Settings → Langflow API Keys → Add New (copy it — shown once).
2. Backend venv — set ENABLE_LANGFLOW_FLOWS=true, LANGFLOW_URL=http://localhost:7860, and LANGFLOW_API_KEY=<the key from the UI> in .env, then start the app as usual. (A no-API-key local shortcut and the underlying LANGFLOW_SECRET_KEY are covered in the docs' Authentication section.)
Docker Compose alternative — instead of the two-venv setup above, the compose stack runs the backend in Docker alongside an optional Langflow container (with the 12 components already bundled), which you enable by flipping ENABLE_LANGFLOW_FLOWS: "true" and uncommenting the Langflow include. Covered in detail in the doc link below.
For the full setup (both the two-venv and Docker Compose paths), configuration reference, flow customization, and the 12-component developer reference, see Langflow Integration and Langflow Components.
MCP Server Setup (Quickstart)
The MCP server (flexible-graphrag-mcp) is a lightweight standalone package that connects MCP clients (Claude Desktop, Cursor, etc.) to the Flexible GraphRAG backend via its REST API.
For full details see flexible-graphrag-mcp/README.md and flexible-graphrag-mcp/QUICK-USAGE-GUIDE.md. For the full list of available MCP tools see MCP Tools for Claude Desktop and Other MCP Clients below.
Steps
-
First terminal — install and run the flexible-graphrag backend (see Python Backend Setup above) — it must be running on
http://localhost:8000. -
Second terminal — install and start the MCP server in HTTP mode:
uv venv venv-mcp --python 3.13 venv-mcp\Scripts\Activate # Windows source venv-mcp/bin/activate # Linux/macOS uv pip install flexible-graphrag-mcp flexible-graphrag-mcp --http --port 3001 -
Third terminal — test with MCP Inspector:
npx @modelcontextprotocol/inspectorOpen the URL printed in the console (token pre-filled), set transport to Streamable HTTP, URL to
http://localhost:3001/mcp, then click Connect. -
Use with Claude Desktop and other MCP clients — see
flexible-graphrag-mcp/README.mdfor stdio transport config and client-specific setup.
MCP Tools for Claude Desktop and Other MCP Clients
The MCP server provides 12 tools for document intelligence workflows (14 with MCP_BROWSER_SIGN_IN=true). Search and query take source_auth (per-user permission filtering) and sources; see Permission filtering: three levels.
