### Install fast-graphrag from PyPi

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/README.md

Install the library using pip for a stable release.

```bash
pip install fast-graphrag
```

--------------------------------

### Install fast-graphrag from source

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/README.md

Use this command to install the library from its source repository. Ensure you have cloned the repository first.

```bash
cd fast_graphrag
poetry install
```

--------------------------------

### Initialize GraphRAG

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Initializes the GraphRAG class with configuration for knowledge base persistence, domain description, example queries, and entity types. The knowledge base persists automatically.

```python
from fast_graphrag import GraphRAG

# Initialize GraphRAG with domain-specific configuration
grag = GraphRAG(
    working_dir="./knowledge_base",
    domain="Analyze technical documentation and identify software components. Focus on APIs, services, data models, and their interconnections.",
    example_queries="\n".join([
        "What components does the authentication service depend on?",
        "How does data flow between the API gateway and backend services?",
        "What are the main entities in the user management system?"
    ]),
    entity_types=["Service", "API", "Database", "Component", "User", "Event"]
)

# The knowledge base persists automatically - reloading from the same working_dir
# will restore all previously inserted data
```

--------------------------------

### Initialize and Use GraphRAG

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/README.md

Initialize the GraphRAG object with domain-specific information and example queries, then insert and query data. The knowledge is retained across sessions if the same working directory is used.

```python
from fast_graphrag import GraphRAG

DOMAIN = "Analyze this story and identify the characters. Focus on how they interact with each other, the locations they explore, and their relationships."

EXAMPLE_QUERIES = [
    "What is the significance of Christmas Eve in A Christmas Carol?",
    "How does the setting of Victorian London contribute to the story's themes?",
    "Describe the chain of events that leads to Scrooge's transformation.",
    "How does Dickens use the different spirits (Past, Present, and Future) to guide Scrooge?",
    "Why does Dickens choose to divide the story into \"staves\" rather than chapters?"
]

ENTITY_TYPES = ["Character", "Animal", "Place", "Object", "Activity", "Event"]

grag = GraphRAG(
    working_dir="./book_example",
    domain=DOMAIN,
    example_queries="\n".join(EXAMPLE_QUERIES),
    entity_types=ENTITY_TYPES
)

with open("./book.txt") as f:
    grag.insert(f.read())

print(grag.query("Who is Scrooge?").response)
```

--------------------------------

### Format References with Custom Logic

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/examples/query_parameters.ipynb

Formats the references from a query answer using a custom lambda function. This example shows how to create a reference string that includes the document index and chunk indices, along with metadata.

```python
fresponse, fcontext = answer.format_references(
    lambda doc_index, chunk_indices, metadata: f"[{doc_index}.{'-'.join(map(str, chunk_indices))}]({metadata['id']})"
)
```

--------------------------------

### Format References with Document URL

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/examples/query_parameters.ipynb

Formats references from a query answer, linking to a document URL stored in the metadata. This example customizes the formatting function to use a 'url' field from the metadata.

```python
fresponse, fcontext = answer.format_references(
    lambda doc_index, chunk_indices, metadata: f"[{doc_index}]({metadata['url']})"
)
```

--------------------------------

### Initialize GraphRAG and Query with Default Parameters

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Initializes the GraphRAG system and demonstrates a basic query. Default QueryParam settings are used.

```python
from fast_graphrag import GraphRAG, QueryParam

grag = GraphRAG(
    working_dir="./configurable_queries",
    domain="Technical documentation analysis",
    example_queries="How do components interact?",
    entity_types=["Component", "API", "Service"]
)

# Default query parameters
default_params = QueryParam()
# with_references=False, only_context=False
# entities_max_tokens=4000, relations_max_tokens=3000, chunks_max_tokens=9000
```

--------------------------------

### Download Sample Data

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/README.md

Download a sample text file to use with the GraphRAG library.

```bash
curl https://raw.githubusercontent.com/circlemind-ai/fast-graphrag/refs/heads/main/mock_data.txt > ./book.txt
```

--------------------------------

### Initialize and Query GraphRAG

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/examples/query_parameters.ipynb

Initializes a GraphRAG instance and performs a query, retrieving only the context without generating an answer. Ensure `working_dir`, `DOMAIN`, `QUERIES`, and `ENTITY_TYPES` are properly configured.

```python
from fast_graphrag import GraphRAG, QueryParam

working_dir = "..."
DOMAIN = "..."
QUERIES = ["...", "..."]
ENTITY_TYPES = ["...", "..."]

grag = GraphRAG(
    working_dir=working_dir,
    domain=DOMAIN,
    example_queries="\n".join(QUERIES),
    entity_types=ENTITY_TYPES,
)

# Inserting some data
corpus = {
    "title1": "corpus1 ...",
    "title2": "corpus2 ...",
}
grag.insert(
    [f"{title}: {corpus}" for title, corpus in tuple(corpus.items())],
    metadata=[{"id": title} for title in tuple(corpus.keys())],
)

# Querying only context
query = "..."
answer = grag.query(query, QueryParam(only_context=True))

print(answer.response)  # ""
print(answer.context)  # {entities: [...], relations: [...], chunks: [...]}
```

--------------------------------

### Evaluate RAG Methods on 2wikimultihopqa (51 queries)

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/benchmarks/README.md

This output shows the retrieval performance for various RAG methods on the 2wikimultihopqa dataset with 51 queries. It details the percentage of queries with perfect retrieval for all queries and multihop-only queries.

```text
Evaluation of the performance of different RAG methods on 2wikimultihopqa (51 queries)

VectorDB
Loading dataset...
[all questions] Percentage of queries with perfect retrieval: 0.49019607843137253
[multihop only] Percentage of queries with perfect retrieval: 0.32432432432432434

LightRAG [local mode]
Loading dataset...
Percentage of queries with perfect retrieval: 0.47058823529411764
[multihop only] Percentage of queries with perfect retrieval: 0.32432432432432434

GraphRAG [local mode]
Loading dataset...
[all questions] Percentage of queries with perfect retrieval: 0.7450980392156863
[multihop only] Percentage of queries with perfect retrieval: 0.6756756756756757

Circlemind
Loading dataset...
[all questions] Percentage of queries with perfect retrieval: 0.9607843137254902
[multihop only] Percentage of queries with perfect retrieval: 0.9459459459459459
```

--------------------------------

### Evaluate RAG Methods on 2wikimultihopqa (101 queries)

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/benchmarks/README.md

This output presents the retrieval performance for different RAG methods on the 2wikimultihopqa dataset using 101 queries. It includes the percentage of queries with perfect retrieval for both all queries and multihop-only queries.

```text
Evaluation of the performance of different RAG methods on 2wikimultihopqa (101 queries)

VectorDB
Loading dataset...
[all questions] Percentage of queries with perfect retrieval: 0.4158415841584158
[multihop only] Percentage of queries with perfect retrieval: 0.2318840579710145

LightRAG [local mode]
Loading dataset...
[all questions] Percentage of queries with perfect retrieval: 0.44554455445544555
[multihop only] Percentage of queries with perfect retrieval: 0.2753623188405797

GraphRAG [local mode]
Loading dataset...
[all questions] Percentage of queries with perfect retrieval: 0.7326732673267327
[multihop only] Percentage of queries with perfect retrieval: 0.6376811594202898

Circlemind
Loading dataset...
[all questions] Percentage of queries with perfect retrieval: 0.9306930693069307
[multihop only] Percentage of queries with perfect retrieval: 0.8985507246376812
```

--------------------------------

### Adjust Token Budgets for Comprehensive Overviews

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Increases token limits for entities, relations, and source text chunks to allow for more detailed context retrieval and comprehensive answers.

```python
# Adjust token budgets for different use cases
detailed_result = grag.query(
    "Give a comprehensive overview",
    params=QueryParam(
        entities_max_tokens=8000,   # More entity context
        relations_max_tokens=6000,  # More relationship context
        chunks_max_tokens=15000     # More source text
    )
)
```

--------------------------------

### Initialize GraphRAG with Checkpointing

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/examples/checkpointing.ipynb

Set `n_checkpoints` to a positive integer `k` to keep the `k` most recent checkpoints. This enables automatic rollback if storage corruption is detected.

```python
from fast_graphrag import GraphRAG

DOMAIN = "Analyze this story and identify the characters. Focus on how they interact with each other, the locations they explore, and their relationships."

EXAMPLE_QUERIES = [
    "What is the significance of Christmas Eve in A Christmas Carol?",
    "How does the setting of Victorian London contribute to the story's themes?",
    "Describe the chain of events that leads to Scrooge's transformation.",
    "How does Dickens use the different spirits (Past, Present, and Future) to guide Scrooge?",
    "Why does Dickens choose to divide the story into \"staves\" rather than chapters?"
]

ENTITY_TYPES = ["Character", "Animal", "Place", "Object", "Activity", "Event"]

grag = GraphRAG(
    working_dir="./book_example",
    n_checkpoints=2,  # Number of checkpoints to keep
    domain=DOMAIN,
    example_queries="\n".join(EXAMPLE_QUERIES),
    entity_types=ENTITY_TYPES
)

with open("./book.txt") as f:
    grag.insert(f.read())

print(grag.query("Who is Scrooge?").response)
```

--------------------------------

### Async API Usage for Non-Blocking Operations

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Utilize `async_insert` and `async_query` for non-blocking document insertion and querying, suitable for integration with async applications. The `show_progress` parameter can be used during insertion.

```python
import asyncio
from fast_graphrag import GraphRAG, QueryParam

async def main():
    grag = GraphRAG(
        working_dir="./async_example",
        domain="Analyze customer feedback and identify sentiments, topics, and issues.",
        example_queries="What are customers complaining about?\nWhat features do users like?",
        entity_types=["Topic", "Sentiment", "Feature", "Issue", "Customer"]
    )

    # Async document insertion
    feedback_documents = [
        "Customer 1: The new dashboard is excellent, very intuitive...",
        "Customer 2: I'm having trouble with the login process...",
        "Customer 3: Great product but the documentation could be better..."
    ]

    num_entities, num_relations, num_chunks = await grag.async_insert(
        feedback_documents,
        metadata=[{"customer_id": i} for i in range(1, 4)],
        show_progress=True
    )

    print(f"Processed feedback: {num_entities} entities extracted")

    # Async query
    result = await grag.async_query(
        "What are the main issues customers are facing?",
        params=QueryParam(with_references=True)
    )

    print(result.response)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Configure Custom OpenAI-Compatible LLM and Embedding Services

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Set up Fast GraphRAG to use custom OpenAI API-compatible language models and embedding services, including Azure OpenAI deployments. Specify model names, base URLs, API keys, and embedding dimensions.

```python
import instructor
from fast_graphrag import GraphRAG
from fast_graphrag._llm import OpenAILLMService, OpenAIEmbeddingService

# Configure with custom OpenAI-compatible endpoints
grag = GraphRAG(
    working_dir="./custom_llm_example",
    domain="Analyze business documents and extract key information.",
    example_queries="What are the main business entities?\nHow are departments connected?",
    entity_types=["Organization", "Department", "Person", "Project", "Resource"],
    config=GraphRAG.Config(
        llm_service=OpenAILLMService(
            model="gpt-4o-mini",
            base_url="https://api.openai.com/v1",  # Or your custom endpoint
            api_key="sk-your-api-key",
            mode=instructor.Mode.JSON
        ),
        embedding_service=OpenAIEmbeddingService(
            model="text-embedding-3-small",
            base_url="https://api.openai.com/v1",
            api_key="sk-your-api-key",
            embedding_dim=1536
        ),
    ),
)
```

--------------------------------

### Set OpenAI API Key

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/README.md

Set your OpenAI API key as an environment variable before running the Python script.

```bash
export OPENAI_API_KEY="sk-..."
```

--------------------------------

### Query with Inline References

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Enable inline references in query responses to trace information back to source documents. Use `format_references` to customize citation appearance.

```python
from fast_graphrag import GraphRAG, QueryParam

grag = GraphRAG(
    working_dir="./research_graph",
    domain="Analyze research papers and identify findings, methods, and conclusions.",
    example_queries="What methods were used?\nWhat are the key findings?",
    entity_types=["Method", "Finding", "Dataset", "Author", "Concept"]
)

# Insert documents with identifying metadata
papers = [
    "Abstract: We propose a novel approach to...",
    "Methods: The experiment was conducted using..."
]
grag.insert(
    papers,
    metadata=[{"id": "paper_001"}, {"id": "paper_002"}]
)

# Query with references enabled
result = grag.query(
    "What methods were used in the research?",
    params=QueryParam(with_references=True)
)

print(result.response)
# Output: The research used a novel approach [1] with experimental methods [2]...

# Format references with custom formatting function
formatted_response, reference_list = result.format_references(
    lambda doc_index, chunk_indices, metadata: f"[{doc_index}]({metadata.get('id', 'unknown')})"
)

print(formatted_response)
# Output: The research used a novel approach [1](paper_001) with experimental methods [2](paper_002)...

print(reference_list)
# Output: {'1': {'meta': {'id': 'paper_001'}, 'chunks': {...}}, '2': {...}}
```

--------------------------------

### Checkpointing for Data Safety

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Enable checkpointing to protect against data corruption. The system automatically maintains a specified number of recent checkpoints and can rollback if necessary.

```python
from fast_graphrag import GraphRAG

# Enable checkpointing with n_checkpoints > 0
grag = GraphRAG(
    working_dir="./checkpointed_graph",
    n_checkpoints=2,  # Keep 2 most recent checkpoints
    domain="Analyze financial documents and track transactions, entities, and relationships.",
    example_queries="What transactions occurred?\nWho are the key parties involved?",
    entity_types=["Transaction", "Account", "Person", "Organization", "Amount"]
)

# Insert data - checkpoints are created automatically
with open("financial_report.txt", "r") as f:
    grag.insert(f.read())

# Query the graph - checkpoints protect against read errors too
result = grag.query("What were the major transactions?")
print(result.response)

# Checkpoints are stored as timestamped directories in working_dir
# e.g., ./checkpointed_graph/1731555907/
# To migrate from no checkpoints: set n_checkpoints and run an insert
# To disable: copy files from latest checkpoint to root, delete checkpoint dirs
```

--------------------------------

### Google Gemini Integration with Rate Limiting

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Integrate GraphRAG with Google Gemini models for LLM and embedding. Configure rate limiting and safety settings for robust performance.

```python
import asyncio
from fast_graphrag import GraphRAG, QueryParam
from fast_graphrag._llm import GeminiLLMService, GeminiEmbeddingService

async def main():
    grag = GraphRAG(
        working_dir="./gemini_example",
        domain="Analyze literature and identify characters, themes, and plot elements.",
        example_queries="Who are the main characters?\nWhat themes are explored?",
        entity_types=["Character", "Theme", "Location", "Event", "Symbol"],
        config=GraphRAG.Config(
            llm_service=GeminiLLMService(
                model="gemini-2.0-flash",
                api_key="your-gemini-api-key",
                temperature=0.7,
                rate_limit_per_minute=True,
                rate_limit_per_second=True,
                max_requests_per_minute=1950,
                max_requests_per_second=500
            ),
            embedding_service=GeminiEmbeddingService(
                model="text-embedding-004",
                api_key="your-gemini-api-key",
                embedding_dim=768,
                max_requests_concurrent=100,
            ),
        ),
    )

    # Insert and query with Gemini
    with open("./book.txt", "r") as f:
        await grag.async_insert(f.read())

    # Gemini supports larger context windows
    result = await grag.async_query(
        "Describe the main character's journey",
        params=QueryParam(
            entities_max_tokens=250000,
            relations_max_tokens=200000,
            chunks_max_tokens=500000
        )
    )
    print(result.response)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Query with Inline References

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Enables inline references within the response for citation tracking, allowing users to see which source chunks contributed to the answer.

```python
# With inline references for citation tracking
referenced_result = grag.query(
    "Explain the architecture",
    params=QueryParam(with_references=True)
)
# Response includes [1], [2], etc. markers pointing to source chunks
```

--------------------------------

### Exporting Knowledge Graph to GraphML

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Export the knowledge graph in GraphML format for visualization or analysis in external tools. Nodes represent entities and edges represent relationships.

```python
from fast_graphrag import GraphRAG

grag = GraphRAG(
    working_dir="./exportable_graph",
    domain="Analyze organizational structure and relationships.",
    example_queries="Who reports to whom?\nWhat teams exist?",
    entity_types=["Person", "Team", "Role", "Project"]
)

# Build the knowledge graph
org_data = """
John is the CEO of TechCorp. Sarah reports to John as VP of Engineering.
Mike and Lisa are senior engineers on Sarah's team. They work on Project Alpha.
The DevOps team, led by Alex, supports Project Alpha infrastructure.
"""
grag.insert(org_data)

# Export to GraphML format
grag.save_graphml("./organization_graph.graphml")

# The exported file can be opened in graph visualization tools
# Nodes represent entities with their types and descriptions
# Edges represent relationships between entities
```

--------------------------------

### Query GraphRAG with References

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/examples/query_parameters.ipynb

Performs a query on a GraphRAG instance, requesting that inline references be included in the answer. This requires setting `with_references=True` in `QueryParam`.

```python
from fast_graphrag import GraphRAG, QueryParam

working_dir = "..."
DOMAIN = "..."
QUERIES = ["...", "..."]
ENTITY_TYPES = ["...", "..."]

grag = GraphRAG(
    working_dir=working_dir,
    domain=DOMAIN,
    example_queries="\n".join(QUERIES),
    entity_types=ENTITY_TYPES,
)

# Inserting some data
corpus = {
    "title1": "corpus1 ...",
    "title2": "corpus2 ...",
}
grag.insert(
    [f"{title}: {corpus}" for title, corpus in tuple(corpus.items())],
    metadata=[{"id": title} for title in tuple(corpus.keys())],
)

# Querying only context
query = "..."
answer = grag.query(query, QueryParam(with_references=True))
```

--------------------------------

### Query in Context-Only Mode

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Retrieves only the relevant context (entities, relations, chunks) without generating an answer. Useful for debugging or when only raw information is needed.

```python
# Context-only mode - skip answer generation, return raw context
context_result = grag.query(
    "What services exist?",
    params=QueryParam(only_context=True)
)
# result.response will be empty string
# result.context contains entities, relations, chunks with relevance scores
for entity, score in context_result.context.entities:
    print(f"Entity: {entity.name} (type: {entity.type}) - relevance: {score:.4f}")
```

--------------------------------

### Query Knowledge Graph

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Searches the knowledge graph using natural language and returns a response generated from retrieved context. Uses PageRank-based exploration for relevant entity, relationship, and source chunk retrieval. Can optionally return only context.

```python
from fast_graphrag import GraphRAG, QueryParam

grag = GraphRAG(
    working_dir="./knowledge_base",
    domain="Analyze stories and identify characters, locations, and events.",
    example_queries="Who are the main characters?\nWhat locations are mentioned?",
    entity_types=["Character", "Location", "Event", "Object"]
)

# Insert some content first
grag.insert("Alice met Bob at the coffee shop downtown. They discussed the upcoming project meeting...")

# Basic query - returns response with context
result = grag.query("Who did Alice meet and where?")
print(result.response)
# Output: Alice met Bob at the coffee shop downtown.
```

```python
# Query with context only (no LLM answer generation)
result = grag.query(
    "What locations are mentioned?",
    params=QueryParam(only_context=True)
)
print(f"Entities found: {len(result.context.entities)}")
print(f"Relations found: {len(result.context.relations)}")
print(f"Source chunks: {len(result.context.chunks)}")
```

--------------------------------

### Insert Documents into GraphRAG

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Processes text content to extract entities, relationships, and build the knowledge graph. Supports single document insertion and batch insertion with optional metadata. Returns counts of extracted entities, relationships, and chunks.

```python
from fast_graphrag import GraphRAG

grag = GraphRAG(
    working_dir="./docs_graph",
    domain="Extract technical concepts and their relationships from documentation.",
    example_queries="How do modules interact?\nWhat are the core components?",
    entity_types=["Module", "Function", "Class", "Concept"]
)

# Insert a single document
with open("documentation.txt", "r") as f:
    content = f.read()

num_entities, num_relations, num_chunks = grag.insert(content)
print(f"Extracted: {num_entities} entities, {num_relations} relationships, {num_chunks} chunks")
# Output: Extracted: 45 entities, 78 relationships, 12 chunks
```

```python
# Insert multiple documents with metadata
documents = [
    "Chapter 1: Introduction to the system architecture...",
    "Chapter 2: API design patterns and best practices...",
    "Chapter 3: Database schema and data modeling..."
]

metadata = [
    {"chapter": 1, "title": "Introduction"},
    {"chapter": 2, "title": "API Design"},
    {"chapter": 3, "title": "Database"}
]

num_entities, num_relations, num_chunks = grag.insert(
    documents,
    metadata=metadata,
    show_progress=True
)
```

--------------------------------

### Azure OpenAI Deployment Configuration

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Configure GraphRAG to use Azure OpenAI for LLM and embedding services. Ensure your deployment name, resource URL, API key, and API version are correctly set.

```python
grag_azure = GraphRAG(
    working_dir="./azure_example",
    domain="Document analysis",
    example_queries="Extract key concepts",
    entity_types=["Concept", "Entity"],
    config=GraphRAG.Config(
        llm_service=OpenAILLMService(
            model="your-deployment-name",
            base_url="https://your-resource.openai.azure.com",
            api_key="your-azure-api-key",
            api_version="2024-02-15-preview",
            client="azure",
            mode=instructor.Mode.JSON
        ),
        embedding_service=OpenAIEmbeddingService(
            model="your-embedding-deployment",
            base_url="https://your-resource.openai.azure.com",
            api_key="your-azure-api-key",
            api_version="2024-02-15-preview",
            client="azure",
            embedding_dim=1536
        ),
    ),
)
```

--------------------------------

### Set Custom Token Limits for Context

Source: https://context7.com/circlemind-ai/fast-graphrag/llms.txt

Adjust token limits for entities, relations, and chunks to control context processing. This is useful for managing memory and performance with large datasets.

```python
result = grag.query(
    "Describe the relationships between characters",
    params=QueryParam(
        entities_max_tokens=8000,
        relations_max_tokens=6000,
        chunks_max_tokens=12000
    )
)
```

--------------------------------

### Set Concurrent Task Limit

Source: https://github.com/circlemind-ai/fast-graphrag/blob/main/README.md

Optionally set a limit for concurrent requests to the LLM, useful for managing local model processing.

```bash
export CONCURRENT_TASK_LIMIT=8
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.