GraphRAG System

GraphRAG (Graph-based Retrieval Augmented Generation) combines vector similarity search with knowledge graph traversal for more accurate and contextual information retrieval.

Overview

ConstellationAPI implements GraphRAG using:

• FalkorDB (via Sagittarius) for unified graph and vector storage
• sentence-transformers for embedding generation
• Hybrid retrieval combining semantic similarity with graph relationships

┌─────────────────────────────────────────────────────────────────┐
│                        Document Upload                           │
│                    (PDF, Excel, Text, etc.)                      │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Document Processor                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Text Extract│  │  Chunking   │  │  Embedding Generation   │ │
│  │ (pypdf,     │──▶│ (recursive, │──▶│  (sentence-transformers)│ │
│  │  openpyxl)  │  │  semantic)  │  │                         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                       FalkorDB Graph                              │
│                                                                  │
│   (Document)──[:HAS_CHUNK]──▶(Chunk {embedding: [...]})         │
│        │                          │                              │
│        │                          └──[:MENTIONS]──▶(Entity)      │
│        │                                              │          │
│        └───────────────────────────────────────────────┘          │
│                    Linked to Ontology Entities                   │
│                  (User, Repository, Issue, etc.)                 │
└─────────────────────────────────────────────────────────────────┘

Embedding Model

Current Model

sentence-transformers/all-mpnet-base-v2

Property	Value
Dimensions	768
Size	~420MB
Speed	Medium
Quality	High-quality semantic similarity

Where Embeddings Are Stored

Embeddings are stored as properties on Chunk nodes in the graph:

// Each chunk has an embedding vector
(Chunk {
  text: "The quarterly report shows...",
  embedding: [0.12, -0.34, 0.56, ...],  // 768 dimensions
  chunk_index: 0,
  tenant_id: "tenant-abc"
})

FalkorDB uses a vector index for efficient similarity search on chunk embeddings (768 dimensions, cosine similarity).

Alternative Models

Model	Dimensions	Quality	Speed	Use Case
all-MiniLM-L6-v2	384	Good	Fast	General, CPU-only
all-mpnet-base-v2 (current)	768	Better	Medium	Balanced quality/speed
e5-large-v2	1024	Excellent	Slow	High accuracy needs
bge-large-en-v1.5	1024	Excellent	Slow	MTEB leaderboard top
gte-large	1024	Excellent	Slow	Large-scale retrieval

To change the model, update /apps/constellation/app/mcp/embeddings.py:

MODEL_NAME = "sentence-transformers/<model-name>"
EMBEDDING_DIM = <dimensions>  # Match model dimensions

warning

Changing the embedding model requires re-indexing all documents and updating the vector index dimension.

---

Document Processing

Supported Formats

Format	Extension	Notes
PDF	.pdf	Text extraction with page boundaries
Excel	.xlsx, .xls	All sheets extracted with headers
Text	.txt	Direct processing
CSV	.csv	Converted to structured text
Markdown	.md	Preserves structure

API Endpoint

POST /documents/upload
Content-Type: multipart/form-data

# Parameters
file: <file>
project_id: "my-project"
tags: "quarterly,finance"
extract_entities: true
chunking_strategy: "recursive"
chunk_size: 1000

Response:

{
  "document_id": "doc_a1b2c3d4e5f6",
  "filename": "Q4-Report.pdf",
  "file_type": "pdf",
  "file_size": 245678,
  "chunk_count": 15,
  "entity_count": 8,
  "message": "Document processed successfully"
}

---

Chunking Strategies

Strategy	Description	Best For
fixed_size	Split at character count	Simple documents
sentence	Split at sentence boundaries	Articles, reports
paragraph	Split at paragraphs	Structured documents
recursive	Try multiple separators	General purpose (default)
semantic	Group by embedding similarity	Long documents

Chunking Parameters

chunk_size: int = 1000      # Target characters per chunk
chunk_overlap: int = 200    # Overlap between chunks

---

Retrieval Modes

Vector Only

Pure semantic similarity search using embeddings.

POST /documents/query
{
  "query": "What are the Q4 revenue projections?",
  "mode": "vector_only",
  "top_k": 5
}

Best for: Document-focused queries where exact wording matters.

Graph Only

Retrieves context based on graph relationships (user context, linked entities).

POST /documents/query
{
  "query": "Show my recent documents",
  "mode": "graph_only",
  "top_k": 5
}

Best for: "Who/what" queries, user-specific context.

Hybrid (Default)

Combines vector similarity with graph context for balanced results.

POST /documents/query
{
  "query": "What's the status of Project Alpha?",
  "mode": "hybrid",
  "top_k": 5,
  "include_context": true
}

Best for: General queries, comprehensive results.

Graph Expanded

Seeds with vector similarity, then expands through graph relationships.

POST /documents/query
{
  "query": "All documents related to the infrastructure team",
  "mode": "graph_expanded",
  "top_k": 10
}

Best for: Complex queries requiring multi-hop reasoning.

---

Graph Schema

Node Types

Node	Properties	Created By
Document	id, filename, file_type, tenant_id	Document upload
Chunk	text, embedding, chunk_index	Document processing
Entity	type, name, source	Entity extraction

Relationships

(Document)-[:HAS_CHUNK]->(Chunk)
(Chunk)-[:MENTIONS]->(Entity)
(Entity)-[:*]->(Entity)  // Ontology relationships

Ontology Integration

GraphRAG chunks are linked to the existing Sagittarius ontology:

          ┌─────────────────────────────────────────────┐
          │            GraphRAG Layer                    │
          │                                              │
          │  (Document)──▶(Chunk)──▶(Entity: "alice")   │
          │                              │               │
          └──────────────────────────────│───────────────┘
                                         │
                        ┌────────────────┘
                        ▼
          ┌─────────────────────────────────────────────┐
          │          Sagittarius Ontology               │
          │                                              │
          │   (User: "alice")──[:AUTHORED_BY]──▶(PR)    │
          │        │                                     │
          │        └──[:BELONGS_TO]──▶(Team)            │
          │                                              │
          └─────────────────────────────────────────────┘

This allows queries like:

• "What documents mention Alice's team?"
• "Find all docs related to repos Alice contributes to"

---

Visualization

Graph Exploration

Use the Constellation API endpoints to explore graph data:

• GET /graph/stats - Node/edge counts by type
• POST /graph/semantic-search - Semantic search across entities and documents
• POST /graph/traverse - Traverse relationships from a starting entity
• GET /graph/me - Personal knowledge graph

---

MCP Integration

GraphRAG is accessible via MCP tools:

Tool	Description
document:upload	Upload and process a document
document:list	List documents for a tenant
document:query	Semantic search with GraphRAG
document:summarize	Generate document summary
document:delete	Remove a document and chunks

Example MCP execution:

POST /mcp/execute
{
  "tool": "document:query",
  "arguments": {
    "query": "What are the key findings?",
    "top_k": 3
  }
}

---

Performance Considerations

Scaling

Scale	Documents	Chunks	Recommendation
Small	< 1,000	< 10,000	Single FalkorDB instance
Medium	1,000 - 50,000	10,000 - 500,000	FalkorDB + more RAM
Large	> 50,000	> 500,000	FalkorDB cluster

Optimization Tips

1. Use tenant_id filters - Always filter by tenant for multi-tenant queries
2. Limit chunk size - Smaller chunks (500-1000 chars) for precise retrieval
3. Index tuning - FalkorDB vector index parameters affect speed/accuracy
4. Batch processing - Upload multiple documents in parallel

---

Related Documentation

• Architecture Guide - System overview
• Document API Reference - REST endpoints
• Sagittarius Guide - Knowledge graph details