Version: 1.0.0 Last Updated: 2026-05-14 Status: Active

bast-ai-graphrag¶

Version: 0.1.3 Module: bast_ai_graphrag Path: src/python/graphrag

Overview¶

Graph-based Retrieval Augmented Generation (GraphRAG) library providing knowledge graph construction, traversal, and retrieval capabilities for enhanced AI responses.

Features¶

Knowledge Graph Operations¶

Node and edge management
Graph traversal algorithms
Subgraph extraction
Community detection

RAG Integration¶

Graph-based context retrieval
Entity linking
Relationship-aware search
Hierarchical summarization

Storage¶

Neo4j integration
In-memory graph support
Graph serialization
Import/export utilities

Dependencies¶

Internal Dependencies¶

Package	Purpose
bast-ai-config	Configuration management

Usage Examples¶

Initialize GraphRAG¶

from bast_ai_graphrag import GraphRAGService

graphrag = GraphRAGService(catname="mycat")

Add Nodes and Edges¶

# Add nodes
graphrag.add_node(
    node_id="entity_1",
    node_type="Person",
    properties={"name": "John Doe", "role": "Engineer"}
)

graphrag.add_node(
    node_id="entity_2",
    node_type="Organization",
    properties={"name": "Acme Corp"}
)

# Add relationship
graphrag.add_edge(
    source="entity_1",
    target="entity_2",
    edge_type="works_at",
    properties={"since": "2020"}
)

Query Graph¶

# Find related entities
related = graphrag.get_related_entities(
    entity_id="entity_1",
    relationship_types=["works_at", "knows"],
    max_depth=2
)

# Get entity context
context = graphrag.get_entity_context(
    entity_id="entity_1",
    include_relationships=True,
    include_neighbors=True
)

Graph Traversal¶

# BFS traversal
nodes = graphrag.traverse_bfs(
    start_node="entity_1",
    max_depth=3,
    filter_types=["Person", "Organization"]
)

# Find paths
paths = graphrag.find_paths(
    source="entity_1",
    target="entity_3",
    max_length=5
)

RAG Context Retrieval¶

# Get context for query
context = graphrag.retrieve_context(
    query="What projects is John working on?",
    entities=["john_doe"],
    context_type="comprehensive",
    max_tokens=2000
)

# Use with LLM
response = llm.generate(
    prompt=f"Context:\n{context}\n\nQuestion: {query}"
)

Community Detection¶

# Detect communities
communities = graphrag.detect_communities(
    algorithm="louvain",
    resolution=1.0
)

# Get community summary
for community_id, members in communities.items():
    summary = graphrag.summarize_community(community_id)
    print(f"Community {community_id}: {summary}")

Testing¶

Unit Tests (3 files)¶

test_edit.py - Graph editing tests
test_export.py - Export functionality tests
test_read.py - Read operation tests

Integration Tests (4 files)¶

delete.py - Deletion tests
edit.py - Editing tests
read.py - Read tests
test1.py - General tests

Running Tests¶

pants test src/python/graphrag:: -- -s --no-header

Configuration¶

# resources/config/{catname}.yaml
graphrag:
  storage:
    type: neo4j  # or "memory"
    uri: ${NEO4J_URI:bolt://localhost:7687}
    user: ${NEO4J_USER:neo4j}
    password: ${NEO4J_PASSWORD}

  retrieval:
    max_depth: 3
    max_context_tokens: 2000
    include_communities: true

  community:
    algorithm: louvain
    resolution: 1.0

Issues & Improvements¶

Current Issues¶

Scale limitations: Large graphs can be slow
Limited algorithms: Few traversal options
No visualization: Can't visualize graphs

Suggested Improvements¶

Graph partitioning: Handle large graphs
More algorithms: Add PageRank, centrality
Visualization: Add graph rendering
Caching: Cache common traversals
Streaming: Stream large results