### Install GraphRAG SDK and Run FalkorDB

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/index.md

Install the GraphRAG SDK with LiteLLM support and start a FalkorDB instance. This is the initial setup for using the SDK.

```bash
pip install graphrag-sdk[litellm]
docker run -p 6379:6379 falkordb/falkordb
```

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

### Quickstart Example

Source: https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/README.md

A minimal example demonstrating the ingest and query process of the GraphRAG SDK.

```python
from graphrag_sdk import GraphRAG

# Initialize the GraphRAG pipeline
rag = GraphRAG()

# Ingest data from a file
rag.ingest("path/to/your/document.txt")

# Query the knowledge graph
response = rag.query("What is the main topic of the document?")
print(response)
```

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

### Install GraphRAG-SDK and Start FalkorDB

Source: https://github.com/falkordb/graphrag-sdk/blob/main/README.md

Installs the GraphRAG-SDK with LiteLLM support and starts a FalkorDB Docker container. Sets the OpenAI API key environment variable. For PDF ingestion, install with the 'pdf' extra.

```bash
pip install graphrag-sdk[litellm]
docker run -d -p 6379:6379 -p 3000:3000 --name falkordb falkordb/falkordb:latest
export OPENAI_API_KEY="sk-..."
```

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

### End-to-End Ontology Evolution Example

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/ontology-evolution.md

This example demonstrates a full lifecycle of ontology evolution, from initial setup to adding attributes, changing types, and discovering new entities.

```python
import asyncio
from graphrag_sdk import (
    Attribute,
    ConnectionConfig,
    Entity,
    EvolutionResult,
    GraphRAG,
    LiteLLM,
    LiteLLMEmbedder,
    Ontology,
    Relation,
)


async def main():
    starter = Ontology(
        entities=[
            Entity(label="Person", description="A human"),
            Entity(label="Company", description="A business"),
        ],
        relations=[
            Relation(
                label="WORKS_AT",
                patterns=[("Person", "Company")],
            ),
        ],
    )

    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="evolve_demo"),
        llm=LiteLLM(model="openai/gpt-4o-mini"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-small"),
        ontology=starter,
    ) as rag:
        # 1. Ingest with the starter ontology.
        await rag.ingest(
            text="Alice Liddell is a software engineer at Acme Corp.",
            document_id="doc1",
        )

        # 2. Atomic attribute add: declare + LLM backfill + commit.
        result: EvolutionResult = await rag.add_attribute(
            "Person", Attribute(name="role", type="STRING"),
        )
        print(f"role filled on {result.values_filled} entities, "
              f"{result.chunks_scanned} chunks scanned, "
              f"{result.llm_calls} LLM calls")

        # 3. Type change via drop + add.
        await rag.drop_attribute("Person", "role")
        result = await rag.add_attribute(
            "Person", Attribute(name="role", type="STRING",
                                description="Their job title"),
        )

        # 4. Declare a new entity type — cheap, no LLM.
        await rag.add_entity(Entity(label="City"))

        # 5. Opportunistic: scan corpus for any Cities we missed.
        discovery = await rag.backfill_entity("City", scope="all")
        print(f"discovered {discovery.values_filled} City instances")

        # 6. Inspect the final ontology.
        ontology = await rag.get_ontology()
        for e in ontology.entities:
            attrs = ", ".join(f"{p.name}:{p.type}" for p in e.properties) or "—"
            print(f"  {e.label:<10} {attrs}")


asyncio.run(main())

```

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

### Start FalkorDB Instance

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/benchmark.md

Use this Docker command to start a FalkorDB instance on the default port.

```bash
docker run -p 6379:6379 falkordb/falkordb:latest
```

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

### Start FalkorDB Instance with Docker Compose

Source: https://github.com/falkordb/graphrag-sdk/blob/main/CONTRIBUTING.md

Start a FalkorDB instance using Docker Compose for integration testing and development.

```bash
docker compose up -d falkordb
```

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

### Install Legacy Release

Source: https://github.com/falkordb/graphrag-sdk/blob/main/README.md

If you are still on the v0.x API, you can pin the legacy release using pip.

```bash
pip install graphrag-sdk==0.8.2
```

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

### Initialize LiteLLM for OpenAI

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Example of initializing the LiteLLM provider for use with OpenAI models. Requires an API key.

```python
llm = LiteLLM(model="gpt-4.1", api_key="sk-...")
```

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

### Install GraphRAG SDK

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/getting-started.md

Install the SDK with all optional dependencies using pip. This command ensures all necessary packages for full functionality are included.

```bash
pip install "graphrag-sdk[all]"
```

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

### GraphRAG SDK Installation Options

Source: https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/README.md

Provides commands for installing the GraphRAG SDK with different feature sets, including support for various LLM providers and document types.

```bash
pip install graphrag-sdk[litellm]       # OpenAI, Azure, Anthropic, 100+ models
```

```bash
pip install graphrag-sdk[openrouter]    # OpenRouter models
```

```bash
pip install graphrag-sdk[pdf]           # PDF ingestion
```

```bash
pip install graphrag-sdk[all]           # Everything
```

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

### Initialize LiteLLM for Azure OpenAI

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Example of initializing the LiteLLM provider for Azure OpenAI services. Requires specific Azure credentials and parameters.

```python
llm = LiteLLM(
    model="azure/gpt-4.1",
    api_key="your-azure-key",
    api_base="https://your-resource.openai.azure.com/",
    api_version="2024-12-01-preview",
    temperature=0.0,
    max_tokens=4096,
)
```

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

### Install GraphRAG SDK

Source: https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/examples/05_notebook_demo.ipynb

Installs the GraphRAG SDK with LiteLLM support. Uncomment this line if running in a Colab or fresh environment.

```python
# Install the SDK (uncomment if running in Colab or fresh environment)
# !pip install graphrag-sdk[litellm]
```

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

### Install GraphRAG SDK and Dependencies

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/benchmark.md

Install the GraphRAG SDK with Litellm support and the gliner library using pip. This command installs the necessary packages for using the SDK and its features.

```bash
pip install graphrag-sdk[litellm] gliner
```

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

### Install GraphRAG SDK Locally

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/getting-started.md

For a local editable installation from a cloned repository, use this pip command. It allows for direct modifications and testing within your local environment.

```bash
pip install -e "./graphrag_sdk[all]"
```

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

### Start FalkorDB with Docker

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/getting-started.md

Run FalkorDB as a Docker container to set up the necessary database. This command maps the default port and names the container 'falkordb'.

```bash
docker run -d --name falkordb -p 6379:6379 falkordb/falkordb
```

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

### Ingest and Query with Different Data Sources

Source: https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/README.md

Shows how to ingest data from PDF files or raw text, finalize the graph indexing, retrieve context, and get a full RAG completion. This example assumes a pre-configured GraphRAG instance.

```python
import asyncio
from graphrag_sdk import GraphRAG, ConnectionConfig, LiteLLM, LiteLLMEmbedder

async def main():
    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="my_graph"),
        llm=LiteLLM(model="openai/gpt-4o"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-small"),
    ) as rag:
        await rag.ingest("report.pdf")                              # PDF
        await rag.ingest("source_id", text="Alice works at Acme.")  # Raw text
        await rag.finalize()                                         # Dedup + index

        # Retrieve context only
        context = await rag.retrieve("Where does Alice work?")

        # Full RAG: retrieve + generate answer
        result = await rag.completion("Where does Alice work?")
        print(result.answer)

asyncio.run(main())
```

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

### Initialize GraphRAG with FalkorDBConnection

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Shows how to initialize GraphRAG by passing a pre-built FalkorDBConnection object for full control over the connection setup.

```python
conn = FalkorDBConnection(ConnectionConfig(host="10.0.0.5", password="secret"))
rag = GraphRAG(connection=conn, llm=my_llm, embedder=my_embedder)
```

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

### Initialize OpenRouter LLM

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Configure an LLM using the OpenRouter provider. This requires the model name, API key, and optionally temperature and max tokens. Install with `pip install graphrag-sdk[openrouter]`.

```python
from graphrag_sdk.core.providers import OpenRouterLLM

llm = OpenRouterLLM(
    model="anthropic/claude-sonnet-4-20250514",
    api_key="sk-or-...",
    temperature=0.0,
    max_tokens=4096,
)
```

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

### Canonical CI Usage Example

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/incremental-updates.md

Provides a canonical example of using `apply_changes` within a `GraphRAG` context in a Continuous Integration pipeline, followed by a `finalize()` call.

```python
async with GraphRAG(connection=..., llm=..., embedder=...) as rag:
    await rag.apply_changes(**parse_git_diff(pr_sha, base_sha))
    await rag.finalize()
```

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

### Install SDK in Editable Mode

Source: https://github.com/falkordb/graphrag-sdk/blob/main/CONTRIBUTING.md

Install the GraphRAG SDK in editable mode, including development dependencies.

```bash
pip install -e "graphrag_sdk[dev]"
```

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

### Quick Start: Ingest and Query with GraphRAG

Source: https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/README.md

Demonstrates the basic usage of the GraphRAG SDK for ingesting a document and answering a question. Requires Python 3.10+ and a running FalkorDB instance.

```python
import asyncio
from graphrag_sdk import GraphRAG, ConnectionConfig, LiteLLM, LiteLLMEmbedder

async def main():
    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="my_graph"),
        llm=LiteLLM(model="openai/gpt-4o"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-small"),
    ) as rag:
        result = await rag.ingest("my_document.txt")
        print(f"Created {result.nodes_created} nodes, {result.relationships_created} edges")

        answer = await rag.completion("What is the main theme?")
        print(answer.answer)

asyncio.run(main())
```

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

### Import GraphRAG

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Import the main GraphRAG class to start using the SDK.

```python
from graphrag_sdk import GraphRAG
```

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

### End-to-End Ontology Discovery and Ingestion Example

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/ontology-discovery.md

This Python script demonstrates the complete workflow of ontology discovery, from bootstrapping a draft from initial sources to ingesting new documents with a curated ontology and suggesting schema extensions. It utilizes LiteLLM for LLM interactions and embeddings, and GraphRAG for ingestion and schema management.

```python
import asyncio
from graphrag_sdk import (
    ConnectionConfig, GraphRAG, LiteLLM, LiteLLMEmbedder, Ontology,
)


async def main():
    llm = LiteLLM(model="gpt-4o-mini")

    # 1. Bootstrap a draft from a small corpus.
    draft = await Ontology.from_sources(
        ["docs/intro.md", "docs/history.pdf"],
        llm,
        boundaries="company history and biographies",
        sample_chunks_per_doc=3,
    )
    draft.save_to_file("ontology.json")
    # Review ontology.json by hand at this point — edit / curate / commit.

    # 2. Ingest with the curated draft.
    rag = GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="discover_demo"),
        llm=llm,
        embedder=LiteLLMEmbedder(model="text-embedding-3-large"),
        embedding_dimension=256,
        ontology=Ontology.from_file("ontology.json"),
    )
    async with rag:
        await rag.ingest(source=["docs/intro.md", "docs/history.pdf"])

        # 3. Later — a new document shows up.
        proposal = await rag.suggest_schema_extensions(
            "docs/acquisition_news.md",
            boundaries="company history and biographies",
        )

        # 4. Apply the additions you accept.
        for entity in proposal.new_entities:
            await rag.add_entity(entity)
        for owner, attribute in proposal.new_attributes:
            await rag.add_attribute(owner, attribute)


asyncio.run(main())
```

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

### Built-in Resolution Strategies

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Examples of built-in resolution strategies, including ExactMatchResolution and DescriptionMergeResolution.

```python
# Built-in:
- ExactMatchResolution(resolve_property="id")
- DescriptionMergeResolution(llm=None, force_summary_threshold=3, max_summary_tokens=500)
```

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

### Custom LLM and Embedder Provider

Source: https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/README.md

Example of integrating a custom LLM and embedder by subclassing the provided interfaces.

```python
from graphrag_sdk import GraphRAG
from graphrag_sdk.llm import LLMInterface
from graphrag_sdk.embedder import Embedder

# Define a custom LLM class
class MyCustomLLM(LLMInterface):
    def __init__(self, model_name):
        super().__init__(model_name)
        # Initialize your custom LLM client here

    def completion(self, prompt, **kwargs):
        # Implement your custom LLM completion logic
        pass

# Define a custom Embedder class
class MyCustomEmbedder(Embedder):
    def __init__(self, model_name):
        super().__init__(model_name)
        # Initialize your custom embedder client here

    def embed(self, texts):
        # Implement your custom embedder logic
        pass

# Initialize GraphRAG with custom providers
rag = GraphRAG(
    llm=MyCustomLLM(model_name="my-custom-llm"),
    embedder=MyCustomEmbedder(model_name="my-custom-embedder")
)

# Ingest and query as usual
rag.ingest("path/to/your/data.txt")
response = rag.query("How does the custom provider affect results?")
print(response)
```

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

### Custom RetrievalStrategy Implementation

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/strategies.md

Example of implementing a custom retrieval strategy by subclassing `RetrievalStrategy` and overriding the `_execute` method for custom logic.

```python
class GlobalRetrieval(RetrievalStrategy):
    async def _execute(self, query, ctx, **kwargs):
        # Your custom retrieval logic
        results = await self.vector_store.search(query_vector, top_k=20)
        return RawSearchResult(records=results)

rag = GraphRAG(connection=conn, llm=llm, embedder=embedder, retrieval_strategy=GlobalRetrieval())
```

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

### Custom Sentence Chunking Strategy Implementation

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/strategies.md

Example of implementing a custom chunking strategy by subclassing ChunkingStrategy. This example uses NLTK for sentence tokenization.

```python
class SentenceChunking(ChunkingStrategy):
    async def chunk(self, text: str, ctx: Context) -> TextChunks:
        import nltk
        sentences = nltk.sent_tokenize(text)
        chunks = []
        for i, sent in enumerate(sentences):
            chunks.append(TextChunk(text=sent, index=i))
        return TextChunks(chunks=chunks)
```

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

### PDF Ingestion with Custom Schema

Source: https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/README.md

Example of ingesting a PDF document and defining a custom schema for extracted information.

```python
from graphrag_sdk import GraphRAG
from graphrag_sdk.strategies import PdfLoader, FixedSizeChunking

# Define a custom schema for extracted entities
custom_schema = {
    "entities": [
        {"name": "Person", "attributes": ["name", "age"]},
        {"name": "Company", "attributes": ["name", "industry"]}
    ]
}

# Initialize GraphRAG with PDF loader and custom schema
rag = GraphRAG(
    loader=PdfLoader(),
    chunking=FixedSizeChunking(chunk_size=500, chunk_overlap=50),
    schema=custom_schema
)

# Ingest a PDF file
rag.ingest("path/to/your/document.pdf")

# Query the knowledge graph
response = rag.query("Who are the key people and companies mentioned?")
print(response)
```

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

### LiteLLM Provider Configuration

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/providers.md

Configuration examples for using LiteLLM as both an LLM and an Embedder. LiteLLM supports a wide range of providers including Azure OpenAI, OpenAI, and Anthropic.

```APIDOC
## LiteLLM LLM Configuration

### Description
Configure the LiteLLM provider for text generation and extraction.

### Method
Instantiate the `LiteLLM` class.

### Parameters
#### Request Body
- **model** (str) - Required - Model identifier (use `provider/model` format for non-OpenAI)
- **api_key** (str | None) - Optional - API key (or set via environment variable)
- **api_base** (str | None) - Optional - Base URL (required for Azure)
- **api_version** (str | None) - Optional - API version (required for Azure)
- **temperature** (float) - Optional - Sampling temperature (default: 0.0)
- **max_tokens** (int | None) - Optional - Max output tokens (default: None)

### Request Example
```python
from graphrag_sdk import LiteLLM

# Azure OpenAI Example
llm = LiteLLM(
    model="azure/gpt-4.1",
    api_key="your-azure-key",
    api_base="https://your-resource.openai.azure.com/",
    api_version="2024-12-01-preview",
    temperature=0.0,
    max_tokens=None
)

# OpenAI Direct Example
llm = LiteLLM(
    model="gpt-4o",
    api_key="your-openai-key"
)

# Anthropic Example
llm = LiteLLM(
    model="anthropic/claude-sonnet-4-20250514",
    api_key="your-anthropic-key"
)
```

## LiteLLM Embedder Configuration

### Description
Configure the LiteLLM provider for generating vector embeddings.

### Method
Instantiate the `LiteLLMEmbedder` class.

### Parameters
#### Request Body
- **model** (str) - Required - Embedding model identifier
- **api_key** (str | None) - Optional - API key
- **api_base** (str | None) - Optional - Base URL
- **api_version** (str | None) - Optional - API version

### Request Example
```python
from graphrag_sdk import LiteLLMEmbedder

# Azure OpenAI Example
embedder = LiteLLMEmbedder(
    model="azure/text-embedding-ada-002",
    api_key="your-azure-key",
    api_base="https://your-resource.openai.azure.com/",
    api_version="2024-12-01-preview"
)

# OpenAI Direct Example
embedder = LiteLLMEmbedder(
    model="text-embedding-3-small",
    api_key="your-openai-key"
)
```
```

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

### Clone Repository and Set Up Virtual Environment

Source: https://github.com/falkordb/graphrag-sdk/blob/main/CONTRIBUTING.md

Clone the GraphRAG SDK repository and set up a Python virtual environment for development.

```bash
git clone https://github.com/FalkorDB/GraphRAG-SDK.git
cd GraphRAG-SDK
python -m venv .venv
source .venv/bin/activate
```

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

### Initialize LLM and Embedder Providers

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/benchmark.md

Set up the Language Model (LLM) and embedding model providers, specifying model names, API keys, base URLs, and versions. Ensure these are correctly configured for your environment.

```python
import asyncio
import json
from graphrag_sdk import ConnectionConfig, GraphRAG, LiteLLM, LiteLLMEmbedder

llm = LiteLLM(
    model="azure/gpt-4o-mini",
    api_key="...",
    api_base="https://your-resource.openai.azure.com/",
    api_version="2024-12-01-preview",
)

embedder = LiteLLMEmbedder(
    model="azure/text-embedding-3-small",
    api_key="...",
    api_base="https://your-resource.openai.azure.com/",
    api_version="2024-12-01-preview",
)
```

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

### LLMInterface Constructor Parameters

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/providers.md

Details the parameters available for initializing the LLMInterface.

```APIDOC
## LLMInterface Constructor Parameters

### Parameters

- **`model_name`** (str) - Model identifier.
- **`model_params`** (dict | None, optional) - Provider-specific parameters. Defaults to None.
- **`max_concurrency`** (int, optional) - Parallel call limit for `abatch_invoke`. Defaults to 12.
```

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

### Cost Preview for Ontology Evolution Operations

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/ontology-evolution.md

Demonstrates how to use the `dry_run=True` option with `add_attribute` to preview the number of chunks that would be scanned without invoking the LLM or performing any writes. This helps in estimating the cost and deciding whether to proceed with the actual operation.

```python
preview = await rag.add_attribute(
    "Person", Attribute(name="role", type="STRING"),
    dry_run=True,
)
print(f"Would scan {preview.chunks_in_scope} chunks "
      f"(~{preview.chunks_in_scope} LLM calls)")
# Decide whether to proceed.
if preview.chunks_in_scope < 1000:
    result = await rag.add_attribute("Person", Attribute(name="role", type="STRING"))
```

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

### Entity Extractor Backends

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Examples of entity extractor backends for GraphExtraction, including GLiNER and LLMExtractor.

```python
# Entity Extractors (step 1 backends for GraphExtraction):
- GLiNERExtractor(threshold=0.75, model_name="urchade/gliner_medium-v2.1") -- default, local NER
- LLMExtractor(llm, threshold=0.75) -- LLM-based NER
- Subclass EntityExtractor for custom backends
```

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

### Initialize LLMExtractor

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/extraction.md

Set up the LLM-based entity extractor. Requires an initialized LLM object and a confidence threshold.

```python
from graphrag_sdk import LLMExtractor

extractor = LLMExtractor(
    llm=my_llm,
    threshold=0.75,
)
```

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

### Delete Document Example

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/incremental-updates.md

Demonstrates how to delete a document by its ID. The `if_missing='ignore'` option prevents errors if the document does not exist.

```python
await rag.delete_document("alice_bio")

# Idempotent cleanup of files removed in a PR — never errors if unknown
await rag.delete_document("some/path.md", if_missing="ignore")
```

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

### Initialize GraphRAG with ConnectionConfig

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Demonstrates initializing the GraphRAG object by passing a ConnectionConfig. The SDK will internally create the FalkorDB connection.

```python
rag = GraphRAG(
    connection=ConnectionConfig(host="localhost", port=6379, graph_name="novels"),
    llm=my_llm,
    embedder=my_embedder,
)
```

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

### FalkorDB Connection Initialization

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Initializes a connection to FalkorDB using the provided configuration. The `config` parameter can be omitted to use default settings.

```python
from graphrag_sdk import FalkorDBConnection

FalkorDBConnection(config: ConnectionConfig | None = None)
```

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

### Define Graph Schema

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Define entities, properties, and relations for your knowledge graph. This schema guides the extraction process.

```python
from graphrag_sdk.core.models import (
    EntityType,
    RelationType,
    PropertyType,
    GraphSchema,
)

schema = GraphSchema(
    entities=[
        EntityType(
            label="Person",
            description="A character or real person",
            properties=[
                PropertyType(name="name", type="STRING", required=True),
                PropertyType(name="age", type="INTEGER"),
                PropertyType(name="occupation", type="STRING"),
            ],
        ),
        EntityType(
            label="Location",
            description="A geographical place or setting",
            properties=[
                PropertyType(name="name", type="STRING", required=True),
                PropertyType(name="country", type="STRING"),
            ],
        ),
        EntityType(
            label="Organization",
            description="A company, institution, or group",
        ),
    ],
    relations=[
        RelationType(
            label="LIVES_IN",
            description="Person resides at location",
            patterns=[("Person", "Location")],
        ),
        RelationType(
            label="WORKS_FOR",
            description="Person is employed by organization",
            patterns=[("Person", "Organization")],
        ),
        RelationType(
            label="LOCATED_IN",
            description="Organization is located at a place",
            patterns=[("Organization", "Location")],
        ),
        RelationType(
            label="KNOWS",
            description="Two people know each other",
            patterns=[("Person", "Person")],
        ),
    ],
)

```

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

### PdfLoader for PDF Files

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/strategies.md

A built-in loader for extracting text from PDF files. Requires the `graphrag-sdk[pdf]` extra to be installed.

```python
from graphrag_sdk.ingestion.loaders.pdf_loader import PdfLoader

loader = PdfLoader()
```

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

### Initialize IngestionPipeline

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Initialize the IngestionPipeline with various strategy and store configurations. The schema and embedder are optional.

```python
IngestionPipeline(
    loader: LoaderStrategy,
    chunker: ChunkingStrategy,
    extractor: ExtractionStrategy,
    resolver: ResolutionStrategy,
    graph_store: GraphStore,
    vector_store: VectorStore,
    schema: GraphSchema | None = None,
    embedder: Embedder | None = None,
)
```

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

### Store Vector in FalkorDB

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/storage.md

Example of how to set a vector property on a node using FalkorDB's native vecf32 type.

```cypher
SET n.embedding = vecf32($vector)
```

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

### Initialize Azure OpenAI LLM with LiteLLM

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Initialize a LiteLLM client for Azure OpenAI using environment variables for authentication and configuration. Ensure the model, API key, base, and version are correctly set.

```python
import os
from graphrag_sdk.core.providers import LiteLLM

llm = LiteLLM(
    model="azure/gpt-4.1",
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_base=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
)
```

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

### Initialize VectorStore

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Initialize the VectorStore with a connection, optional embedder, and configuration for index name, embedding dimension, and similarity function.

```python
VectorStore(connection, embedder=None, index_name="chunk_embeddings", embedding_dimension=256, similarity_function="cosine")
```

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

### OpenRouter Provider Configuration

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/providers.md

Configuration examples for using OpenRouter as both an LLM and an Embedder. OpenRouter provides a unified API for various LLM models.

```APIDOC
## OpenRouter LLM Configuration

### Description
Configure the OpenRouter provider for text generation and extraction.

### Method
Instantiate the `OpenRouterLLM` class.

### Parameters
#### Request Body
- **model** (str) - Required - Model identifier (e.g., `anthropic/claude-sonnet-4-20250514`)
- **api_key** (str) - Required - OpenRouter API key (or set `OPENROUTER_API_KEY` environment variable)
- **temperature** (float) - Optional - Sampling temperature (default: 0.0)
- **max_tokens** (int | None) - Optional - Max output tokens (default: None)
- **extra_headers** (dict) - Optional - Custom headers to include in the request.

### Request Example
```python
from graphrag_sdk import OpenRouterLLM

llm = OpenRouterLLM(
    model="anthropic/claude-sonnet-4-20250514",
    api_key="your-openrouter-key",
    temperature=0.0,
    max_tokens=None,
    extra_headers={}
)
```

## OpenRouter Embedder Configuration

### Description
Configure the OpenRouter provider for generating vector embeddings.

### Method
Instantiate the `OpenRouterEmbedder` class.

### Parameters
#### Request Body
- **model** (str) - Required - Embedding model identifier (e.g., `openai/text-embedding-ada-002`)
- **api_key** (str) - Required - OpenRouter API key (or set `OPENROUTER_API_KEY` environment variable)
- **extra_headers** (dict) - Optional - Custom headers to include in the request.

### Request Example
```python
from graphrag_sdk import OpenRouterEmbedder

embedder = OpenRouterEmbedder(
    model="openai/text-embedding-ada-002",
    api_key="your-openrouter-key",
    extra_headers={}
)
```
```

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

### Configure LiteLLM LLM for OpenAI

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/providers.md

Instantiate the LiteLLM LLM provider for direct OpenAI access. Provide the model name and API key. The temperature and max_tokens parameters can be adjusted.

```python
# OpenAI direct
llm = LiteLLM(
    model="gpt-4o",
    api_key="your-openai-key",
)
```

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

### Initialize Graph Extraction (Default)

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Initialize GraphExtraction using GLiNER for entity NER and an LLM for relationship extraction. Requires an LLM provider.

```python
from graphrag_sdk import GraphExtraction, GLiNERExtractor, LLMExtractor

# Default: GLiNER for entity NER, LLM for relationship extraction
extractor = GraphExtraction(llm=my_llm)

result = await rag.ingest("document.txt", extractor=extractor)

```

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

### Enable Coreference Resolution in GraphExtraction

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/strategies.md

Integrate coreference resolution into the GraphExtraction process to improve entity linking. Requires installing the 'fastcoref' extra for the SDK.

```python
from graphrag_sdk import GraphExtraction, FastCorefResolver

extractor = GraphExtraction(
    llm=llm,
    coref_resolver=FastCorefResolver(),  # pip install graphrag-sdk[fastcoref]
)
```

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

### Custom HtmlLoader Implementation

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/strategies.md

Example of writing a custom `LoaderStrategy` to parse HTML files using BeautifulSoup. This custom loader is then used with the `ingest` method.

```python
class HtmlLoader(LoaderStrategy):
    async def load(self, source: str, ctx: Context) -> DocumentOutput:
        from bs4 import BeautifulSoup
        with open(source) as f:
            soup = BeautifulSoup(f.read(), "html.parser")
        return DocumentOutput(text=soup.get_text())

await rag.ingest("page.html", loader=HtmlLoader())
```

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

### Initialize GraphStore

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Initialize the GraphStore with a FalkorDBConnection. This class handles interactions with the graph database.

```python
GraphStore(connection: FalkorDBConnection)
```

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

### Initialize Graph Extraction with Coreference Resolution

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/extraction.md

Instantiate GraphExtraction with a FastCorefResolver to enable coreference resolution before entity and relationship extraction. Ensure `graphrag-sdk[fastcoref]` is installed.

```python
from graphrag_sdk import FastCorefResolver

extractor = GraphExtraction(
    llm=llm,
    coref_resolver=FastCorefResolver(),  # pip install graphrag-sdk[fastcoref]
)
```

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

### Initialize Context

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Initialize the Context object for managing execution state, including tenant ID and latency budget.

```python
Context(tenant_id: str = "default", latency_budget_ms: float = 60000.0)
```

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

### Ingest and Update Documents

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/incremental-updates.md

Demonstrates initial ingestion, touch-only updates that short-circuit, and real edits that replace chunks and prune orphan entities.

```python
await rag.ingest(text=V1_TEXT, document_id="alice_bio")

result = await rag.update(text=V1_TEXT, document_id="alice_bio")
assert result.no_op is True

result = await rag.update(text=V2_TEXT, document_id="alice_bio")
print(f"replaced {result.chunks_deleted} chunks, "
      f"removed {result.entities_deleted} orphan entities, "
      f"wrote {result.chunks_indexed} new chunks")
```

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

### Configure GraphExtraction with Entity Types

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/strategies.md

Specify entity types for biomedical or legal domains when initializing GraphExtraction. This guides the extraction process to focus on relevant entities.

```python
extractor = GraphExtraction(
    llm=llm,
    entity_types=["Gene", "Protein", "Disease", "Drug", "Pathway"],
)

# Legal domain
extractor = GraphExtraction(
    llm=llm,
    entity_types=["Person", "Organization", "Law", "Court", "Jurisdiction", "Date"],
)
```

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

### Get Graph Statistics

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/graph-schema.md

Retrieves statistics about the graph, such as node and edge counts, entity and relationship types, and density. This is useful for understanding the scale and structure of the graph.

```python
stats = await rag.graph_store.get_statistics()
# Returns: node_count, edge_count, entity_types, relationship_types,
#          graph_density, embedded_relationship_count, mention_edge_count,
#          relates_edge_count
```

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

### Create GraphRAG Instance

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/benchmark.md

Instantiate the GraphRAG client, providing connection details for the database and the initialized LLM and embedder. The connection config specifies the host, port, and graph name.

```python
rag = GraphRAG(
    connection=ConnectionConfig(host="localhost", port=6379, graph_name="novel_bench"),
    llm=llm,
    embedder=embedder,
)
```

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

### MarkdownLoader for Markdown Files

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/strategies.md

A built-in loader for extracting text from Markdown files. Requires the `graphrag-sdk[markdown]` extra to be installed. Preserves markdown syntax for complex elements.

```python
from graphrag_sdk.ingestion.loaders.markdown_loader import MarkdownLoader

loader = MarkdownLoader()
```

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

### Configure LiteLLM LLM for Azure OpenAI

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/providers.md

Instantiate the LiteLLM LLM provider for Azure OpenAI. Ensure to set the model, API key, base URL, and API version. Optional parameters like temperature and max_tokens can also be configured.

```python
from graphrag_sdk import LiteLLM

# Azure OpenAI
llm = LiteLLM(
    model="azure/gpt-4.1",
    api_key="your-azure-key",
    api_base="https://your-resource.openai.azure.com/",
    api_version="2024-12-01-preview",
    temperature=0.0,      # default: 0.0
    max_tokens=None,      # default: None (provider default)
)
```

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

### Create Custom SpaCy Entity Extractor

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/extraction.md

Subclass EntityExtractor to integrate spaCy for NER. This example loads a small English model and processes text to extract entities.

```python
from graphrag_sdk import EntityExtractor
from graphrag_sdk.core.models import ExtractedEntity

class SpaCyExtractor(EntityExtractor):
    def __init__(self, model_name="en_core_web_sm"):
        import spacy
        self._nlp = spacy.load(model_name)

    async def extract_entities(self, text, entity_types, source_chunk_id):
        import asyncio
        doc = await asyncio.to_thread(self._nlp, text)
        return [
            ExtractedEntity(
                name=ent.text,
                type=ent.label_,
                description="",
                source_chunk_ids=[source_chunk_id],
                spans={source_chunk_id: [{"start": ent.start_char, "end": ent.end_char}]}
            )
            for ent in doc.ents
        ]
```

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

### GraphRelationship Data Model

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Represents an edge in the knowledge graph, connecting two nodes. It includes IDs of the start and end nodes, the relationship type, and associated properties.

```python
class GraphRelationship(DataModel):
    start_node_id: str
    end_node_id: str
    type: str                                            # Edge type (RELATES for all extracted rels)
    properties: dict[str, Any] = {}
    embedding_properties: dict[str, list[float]] | None = None
```

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

### Configure OpenRouter LLM

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/providers.md

Instantiate the OpenRouter LLM provider. Specify the model, API key (or environment variable), and optionally configure temperature, max_tokens, and extra headers.

```python
from graphrag_sdk import OpenRouterLLM

llm = OpenRouterLLM(
    model="anthropic/claude-sonnet-4-20250514",
    api_key="your-openrouter-key",      # or set OPENROUTER_API_KEY env var
    temperature=0.0,
    max_tokens=None,
    extra_headers={},
)
```

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

### Basic GraphRAG Pipeline with LiteLLM

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/index.md

Demonstrates a basic GraphRAG pipeline using LiteLLM for LLM and embeddings. This snippet shows how to ingest a document, finalize the graph, and ask a question.

```python
import asyncio
from graphrag_sdk import GraphRAG, ConnectionConfig, LiteLLM, LiteLLMEmbedder

async def main():
    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="my_graph"),
        llm=LiteLLM(model="openai/gpt-4o"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-small"),
    ) as rag:
        await rag.ingest("my_document.pdf")
        await rag.finalize()
        answer = await rag.completion("What is the main topic?")
        print(answer.answer)

asyncio.run(main())
```

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

### Expand Relationships in GraphRAG

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/retrieval.md

Traverses the graph starting from discovered entities to find their direct (1-hop) and indirect (2-hop) relationships. Returns formatted relationship strings with evidence.

```python
expand_relationships()
```

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

### Implement a Custom Entity Extractor with SpaCy

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/strategies.md

Create a custom entity extractor by subclassing `EntityExtractor` and implementing the `extract_entities` method. This example uses SpaCy for Named Entity Recognition.

```python
from graphrag_sdk import EntityExtractor, GraphExtraction
from graphrag_sdk.core.models import ExtractedEntity

class SpaCyExtractor(EntityExtractor):
    def __init__(self, model_name="en_core_web_sm"):
        import spacy
        self._nlp = spacy.load(model_name)

    async def extract_entities(self, text, entity_types, source_chunk_id):
        import asyncio
        doc = await asyncio.to_thread(self._nlp, text)
        return [
            ExtractedEntity(
                name=ent.text,
                type=ent.label_,
                description="",
                source_chunk_ids=[source_chunk_id],
                spans={source_chunk_id: [{"start": ent.start_char, "end": ent.end_char}]}
            )
            for ent in doc.ents
        ]

# Use it
extractor = GraphExtraction(llm=llm, entity_extractor=SpaCyExtractor())
await rag.ingest("doc.txt", extractor=extractor)
```

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

### Create ConnectionConfig from URL

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Parses a redis:// URL to create a ConnectionConfig object. Any provided keyword arguments will override values parsed from the URL.

```python
config = ConnectionConfig.from_url(
    "redis://user:pass@my-falkordb.example.com:6380",
    graph_name="my_graph",
    query_timeout_ms=15_000,
)
```

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

### Generate Answer with Context Inspection

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/getting-started.md

Call `completion` with `return_context=True` to get the generated answer along with the specific chunks and entities used by the retriever. This aids in understanding the RAG process.

```python
result = await rag.completion("Who works at Acme Corp?", return_context=True)
for item in result.retriever_result.items:
    print(f"[{item.metadata.get('section', '')}] {item.content[:100]}...")
```

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

### Configure OpenRouter Embedder

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/providers.md

Instantiate the OpenRouter Embedder provider. Provide the model name and API key. Optional extra headers can also be included.

```python
from graphrag_sdk import OpenRouterEmbedder

embedder = OpenRouterEmbedder(
    model="openai/text-embedding-ada-002",
    api_key="your-openrouter-key",
    extra_headers={},
)
```

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

### LiteLLM Provider Configuration

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/api-reference.md

Initializes the LiteLLM provider, allowing configuration of the model, API key, base URL, and other parameters like temperature and token limits.

```python
LiteLLM(model: str, *, api_key=None, api_base=None, api_version=None, temperature=0.0, max_tokens=None, **kwargs)
```

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

### Get Graph Statistics

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/getting-started.md

Use `get_statistics()` on the `graph_store` to retrieve a summary of the graph's contents, including node and edge counts. This is helpful for understanding the scale and structure of your graph data.

```python
stats = await rag.graph_store.get_statistics()
print(f"Nodes: {stats['node_count']}, Edges: {stats['edge_count']}")
```

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

### Custom LLM Provider Implementation

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/providers.md

Guidance on creating a custom LLM provider by subclassing `LLMInterface` for integration with unsupported LLM services.

```APIDOC
## Custom LLM Provider (LLMInterface ABC)

### Description
Implement a custom LLM provider by subclassing `LLMInterface` to integrate with LLM services not covered by default providers.

### Method
Subclass `LLMInterface` and implement the `invoke` method.

### Required Method
- **invoke(self, prompt: str, **kwargs) -> LLMResponse**: Synchronous text generation.

### Request Example
```python
from graphrag_sdk import LLMInterface
from graphrag_sdk.core.models import LLMResponse

class MyLLM(LLMInterface):
    def __init__(self, model_name: str = "my-model", **kwargs):
        super().__init__(model_name=model_name)
        # Initialize your custom client here
        # Example: self.client = MyCustomLLMClient(**kwargs)

    def invoke(self, prompt: str, **kwargs) -> LLMResponse:
        """Synchronous text generation. REQUIRED."""
        # Replace with your actual client call
        # response = self.client.generate(prompt, **kwargs)
        # return LLMResponse(content=response.text)
        
        # Placeholder response for demonstration
        print(f"Received prompt: {prompt}")
        return LLMResponse(content="This is a custom LLM response.")

# Example usage:
# custom_llm = MyLLM(model_name="my-custom-gpt", api_key="my-key")
# result = custom_llm.invoke("Hello, world!")
# print(result.content)
```
```

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

### Retrieve Context from Knowledge Graph

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/getting-started.md

Use the `retrieve` method to get relevant context for a query without generating an answer. Useful for inspecting retrieved information or custom LLM processing.

```python
context = await rag.retrieve("Who works at Acme Corp?")
for item in context.items:
    print(f"[{item.score:.2f}] {item.content[:100]}...")
```

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

### Initialize GraphRAG Instance

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/getting-started.md

Initialize the GraphRAG instance with connection details, LLM, embedder, and the defined schema. Ensure the embedding dimension matches your model.

```python
from graphrag_sdk import GraphRAG, ConnectionConfig, LiteLLM, LiteLLMEmbedder

rag = GraphRAG(
    connection=ConnectionConfig(host="localhost", graph_name="my_graph"),
    llm=LiteLLM(model="azure/gpt-4.1"),
    embedder=LiteLLMEmbedder(model="azure/text-embedding-3-large", dimensions=256),
    schema=schema,
    embedding_dimension=256,  # must match your embedding model's output dimension
)
```

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

### Initialize MultiPathRetrieval Strategy

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Configure the default `MultiPathRetrieval` strategy with parameters like `chunk_top_k`, `max_entities`, and `max_relationships` to tune search behavior.

```python
from graphrag_sdk.retrieval.strategies.multi_path import MultiPathRetrieval

retriever = MultiPathRetrieval(
    graph_store=rag.graph_store,
    vector_store=rag.vector_store,
    embedder=rag.embedder,
    llm=rag.llm,
    chunk_top_k=20,           # more passages for complex questions
    max_entities=40,          # wider entity coverage
    max_relationships=30,     # more graph context
    rel_top_k=20,             # more RELATES edge hits
    keyword_limit=12,         # extract more keywords
)

result = await rag.completion("What happened?", strategy=retriever)
```

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

### Initialize LiteLLMEmbedder for Azure OpenAI

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Configure the LiteLLMEmbedder for Azure OpenAI, specifying the model, API key, base URL, API version, and batch size. Batch embedding is crucial for performance.

```python
from graphrag_sdk.core.providers import LiteLLMEmbedder

# Azure OpenAI
embedder = LiteLLMEmbedder(
    model="azure/text-embedding-ada-002",
    api_key="your-key",
    api_base="https://your-resource.openai.azure.com/",
    api_version="2024-12-01-preview",
    batch_size=500,
)
```

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

### Initialize OpenRouter Embedder

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Configure OpenRouterEmbedder with model, API key, and batch size. The default batch size is 2048.

```python
from graphrag_sdk.core.providers import OpenRouterEmbedder

embedder = OpenRouterEmbedder(
    model="openai/text-embedding-ada-002",
    api_key="sk-or-...",
    batch_size=2048,
)
```

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

### Custom Strategies Pipeline

Source: https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/README.md

Demonstrates building a GraphRAG pipeline with custom strategies for chunking and retrieval, aiming for benchmark-winning performance.

```python
from graphrag_sdk import GraphRAG
from graphrag_sdk.strategies import ContextualChunking, MultiPathRetrieval

# Initialize GraphRAG with custom strategies
rag = GraphRAG(
    chunking=ContextualChunking(context_window=100, strategy="sentence"),
    retrieval=MultiPathRetrieval(num_paths=5)
)

# Ingest data
rag.ingest("path/to/your/data.txt")

# Query the knowledge graph
response = rag.query("What are the main challenges discussed?")
print(response)
```

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

### Initialize Graph Extraction (Custom GLiNER Threshold)

Source: https://github.com/falkordb/graphrag-sdk/blob/main/docs/configuration.md

Initialize GraphExtraction with a custom confidence threshold for the GLiNER entity extractor. Requires an LLM provider.

```python
from graphrag_sdk import GraphExtraction, GLiNERExtractor, LLMExtractor

# GLiNER with lower confidence threshold
extractor = GraphExtraction(
    llm=my_llm,
    entity_extractor=GLiNERExtractor(threshold=0.6),
)

result = await rag.ingest("document.txt", extractor=extractor)

```