# falkordb/graphrag-sdk architecture

> Architecture diagram of the GitHub repository falkordb/graphrag-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/falkordb/graphrag-sdk
- Repository: https://github.com/falkordb/graphrag-sdk

## Overview

Based on our analysis of both the file tree and the README, GraphRAG-SDK is a Python toolkit for building Graph Retrieval-Augmented Generation (RAG) systems. Its primary purpose is to make it easier to build GenAI applications by integrating knowledge graphs, automated ontology extraction, and multiple LLM providers (for example, OpenAI, Azure OpenAI, Gemini, LiteLLM, and Ollama) into a seamless retrieval-augmented workflow.

##### Main Components
- The Core SDK Module (graphrag_sdk): This is the heart of the project. It contains major sub-components:
– Agents (in agents/ directory) which include classes like KGAgent.
– Document Handling and Loaders (document_loaders/): Supports various file formats (CSV, HTML, JSONL, PDF, plain text, URLs).
– Models (models/) which provide wrappers for LLM providers such as Azure OpenAI, OpenAI, Gemini, LiteLLM, Ollama.
– Ontology and Knowledge Graph Building (ontology.py, kg.py, model_config.py): This includes ontology creation, automated extraction, and configuring a knowledge graph.
– Orchestrator (orchestrator/): Manages the execution plan, decision logic, and multi-agent coordination.
– Steps (steps/ and orchestrator/steps/): Specific routines for query processing (e.g., QA steps, cypher generation, streaming responses).
- External Dependencies and Data:
– Document Sources: Data inputs from numerous examples in movies, trip, and ufc folders.
– FalkorDB or similar graph database backends for storage and high-performance graph querying.
– LLM provider interfaces, which connect to external APIs from OpenAI, Google, Azure, etc.
- Tests & Examples:
– The tests and examples folders provide context on how components interact. They are useful to illustrate sample workflows (e.g., creating ontologies, starting chat sessions, and agent orchestration).

##### Relationships and Interactions
- Data Flow begins with the document loaders that ingest unstructured data. Documents are then processed to allow for ontology extraction.
- The Ontology module converts the processed text/documents into a formal knowledge representation.
- The Knowledge Graph component uses the ontology and the document content to build a graph (backed by a database like FalkorDB).
- Model wrappers (LLM integrations) are responsible for generating responses, creating cypher queries, or performing QA based on the graph data.
- Agents and the Orchestrator coordinate query resolution – agents specialize in domains (restaurants, attractions, etc.), and the orchestrator manages multi-agent workflows for complete use-case scenarios.
- High-level interaction: a client (user code or a chat session) interacts through a chat API that queries the KG. The orchestration layer then directs parts of the query to the proper agents and uses LLM models for answer generation.

##### Architectural Patterns and Design Principles
- Modular Design: Clear separation of concerns (each major functionality is placed in its own sub-package: agents, document loaders, models, orchestrator, steps, etc.).
- Plug-and-Play:
– The SDK can support multiple LLM providers via dedicated modules.
– Document loaders support various file types, suggesting extensibility.
- Orchestration and Decoupled Communication: The orchestrator abstracts multi-agent coordination, where each agent is specialized yet decoupled.
- External Integration: It directly integrates with external APIs and a graph database – showing layered architecture with external dependency layers.

##### Relevant Technologies, Frameworks, and Elements
- Python (the project is written entirely in Python).
- Docker (with provided docker-compose files) and Continuous Integration (observed via .github/workflows).
- External LLM Providers and Graph Databases (FalkorDB).
- Support for various document processing libraries likely used for file parsing and ingestion.

##### Attention to Detail
- Essential architectural elements such as modular design, external integrations, and layered data processing (from ingestion to query answer).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    UC["User Chat Interface"]:::external
    LLM_API["External LLM APIs"]:::external
    GraphDB["Graph Database (FalkorDB)"]:::external

    %% Core SDK Module Subgraph
    subgraph "GraphRAG-SDK Core"
        DL["Document Loaders (CSV,HTML,JSONL,PDF,Text,URL)"]:::core
        Onto["Ontology Extraction Module"]:::core
        KG["Knowledge Graph Builder (KG)"]:::core
        MW["LLM Model Wrappers"]:::core
        AG["Agent System (KGAgent & Agents)"]:::core
        ORCH["Orchestrator (Multi-Agent Coordination)"]:::core
        STEP["Query Processing Steps"]:::core
    end

    %% Data Flow Connections
    UC -->|"query"| ORCH

    DL -->|"ingest_docs"| Onto
    Onto -->|"generate_ontology"| KG
    KG -->|"graph_query"| GraphDB

    ORCH -->|"coordinate_agents"| AG
    ORCH -->|"execute_steps"| STEP
    AG -->|"use_models"| MW
    MW -->|"LLM_API_call"| LLM_API

    %% Styling Classes
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;

    %% Click Events
    click DL "https://github.com/falkordb/graphrag-sdk/tree/main/graphrag_sdk/document_loaders/"
    click Onto "https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/ontology.py"
    click KG "https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/kg.py"
    click MW "https://github.com/falkordb/graphrag-sdk/tree/main/graphrag_sdk/models/"
    click AG "https://github.com/falkordb/graphrag-sdk/blob/main/graphrag_sdk/agents/kg_agent.py"
    click ORCH "https://github.com/falkordb/graphrag-sdk/tree/main/graphrag_sdk/orchestrator/"
    click STEP "https://github.com/falkordb/graphrag-sdk/tree/main/graphrag_sdk/steps/"
```
