# spcl/knowledge-graph-of-thoughts architecture

> Architecture diagram of the GitHub repository spcl/knowledge-graph-of-thoughts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spcl/knowledge-graph-of-thoughts
- Repository: https://github.com/spcl/knowledge-graph-of-thoughts

## Overview

##### Project type and purpose
- This is a modular AI-assistant framework (“Knowledge Graph of Thoughts” or KGoT) plus an evaluation pipeline (GAIA) and a standalone visualization tool.
- Key purpose: orchestrate LLM-based reasoning, dynamically build a knowledge graph, invoke external tools in secure sandboxes, and evaluate on the GAIA benchmark.

##### File structure
- Top level:
- `kgot/` – core Python package with submodules:
– controller (pipeline orchestrator)
– knowledge_graph (graph‐store abstraction over Neo4j or networkX)
– tools (tool‐invocation interfaces, isolated code execution)
– prompts, utils, config files, CLI entrypoint (`__main__.py`)
- `GAIA/` – dataset fetchers, baselines, evaluation script (`gaia.py`), plotters
- `docker_instances/` – container definitions for Neo4j, Python Code Tool, KGoT dependencies
- Configuration files: Docker Compose files, `.env`, `pyproject.toml`, JSON configs (`config_llms.json`, `config_tools.json`).

##### README insights
- Three main components in architecture overview:
a. Controller – orchestrates reasoning loop
b. Graph Store – pluggable backends (Neo4j via Docker, or in-process networkX)
c. Integrated Tools – Python code sandbox, web crawler, math solver, etc.
- CLI entrypoint `kgot`, plus GAIA evaluation script and visualization subproject.

##### Detail
- Both supported graph backends as distinct modules
- Tool manager dispatching to multiple tool‐specific containers or HTTP clients
- GAIA dataset fetch & evaluation as a side‐pipeline
- Snapshot visualization full-stack subproject as an optional consumer of outputs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI / Runner Layer
    subgraph "CLI / Runner Layer"
        direction TB
        CLI["kgot CLI"]:::orchestration
        GAIA["GAIA Evaluation Script"]:::eval
        MULTIGAIA["Multi-run GAIA Helper"]:::eval
    end

    %% Controller Layer
    subgraph "Controller (Orchestration Engine)" 
        direction TB
        CTRL_IF["Controller Interface"]:::orchestration
        subgraph "Neo4j Retrieval Strategies"
            direction TB
            NEO_DIRECT["Direct Mode Controller"]:::orchestration
            NEO_QUERY["Query Mode Controller"]:::orchestration
        end
        subgraph "NetworkX Retrieval Strategies"
            direction TB
            NX_DIRECT["Direct Mode Controller"]:::orchestration
            NX_QUERY["Query Mode Controller"]:::orchestration
        end
    end

    %% Knowledge Graph Store
    subgraph "Knowledge Graph Store"
        direction TB
        KG_IF["Graph-store Interface"]:::datastore
        NEO_BACKEND["Neo4j Backend"]:::datastore
        NX_BACKEND["NetworkX Backend"]:::datastore
    end

    %% Integrated Tools
    subgraph "Integrated Tools (Sandboxed)"
        direction TB
        TOOL_IF["Tool Manager Interface"]:::external
        PY_CODE["Python Code Execution Tool"]:::external
        subgraph "Tools v2.3 Suite"
            direction TB
            TV2_IF["v2.3 Tool Manager"]:::external
            TV2_INDIV["Individual Tools"]:::external
        end
    end

    %% LLM Endpoint
    LLM["Local Ollama API"]:::external

    %% GAIA Dataset & Evaluation
    subgraph "GAIA Dataset & Evaluation"
        direction TB
        GAIA_FETCH["Dataset Fetcher"]:::eval
        GAIA_BASE["Baseline Runners"]:::eval
        GAIA_SCORE["Scoring Script"]:::eval
        subgraph "GAIA Plotters"
            direction TB
            PLOT_ANSWER["Answer Plot"]:::eval
            PLOT_COST["Cost Plot"]:::eval
            PLOT_LEADER["Leaderboard Plot"]:::eval
        end
    end

    %% Docker Containers
    subgraph "Docker Container Definitions"
        direction TB
        DC_NEO["Neo4j Container"]:::external
        DC_PYTOOL["Python Code Tool Container"]:::external
        DC_KGOT["KGoT Dependency Container"]:::external
    end

    %% Snapshots Visualization Tool
    subgraph "Snapshots Visualization Tool"
        direction TB
        VIS_BACK["FastAPI Backend"]:::ui
        VIS_FRONT["Next.js Frontend"]:::ui
    end

    %% Connections
    CLI -->|"starts"| CTRL_IF
    GAIA -->|"invokes"| CTRL_IF
    MULTIGAIA -->|"runs multiple"| GAIA
    CTRL_IF -->|uses| NEO_DIRECT
    CTRL_IF -->|uses| NEO_QUERY
    CTRL_IF -->|uses| NX_DIRECT
    CTRL_IF -->|uses| NX_QUERY
    NEO_DIRECT -->|via| KG_IF
    NEO_QUERY -->|via| KG_IF
    NX_DIRECT -->|via| KG_IF
    NX_QUERY -->|via| KG_IF
    KG_IF -->|to| NEO_BACKEND
    KG_IF -->|to| NX_BACKEND
    CTRL_IF -->|"dispatch"| TOOL_IF
    TOOL_IF -->|executes| PY_CODE
    TOOL_IF -->|manages| TV2_IF
    TV2_IF -->|loads| TV2_INDIV
    CTRL_IF -->|"calls"| LLM
    CTRL_IF -->|"writes snapshots"| VIS_BACK
    CTRL_IF -->|writes snapshots| VIS_BACK
    GAIA_FETCH -->|feeds| GAIA_BASE
    GAIA_BASE -->|evaluates| GAIA_SCORE
    GAIA_SCORE -->|generates| PLOT_ANSWER
    GAIA_SCORE -->|generates| PLOT_COST
    GAIA_SCORE -->|generates| PLOT_LEADER
    VIS_FRONT -->|requests| VIS_BACK

    %% Container boundaries
    CTRL_IF -.->|HTTP RPC| DC_KGOT
    NEO_BACKEND -.->|Bolt| DC_NEO
    PY_CODE -.->|Docker RPC| DC_PYTOOL

    %% Click Events
    click CLI "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/__main__.py"
    click GAIA "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/GAIA/gaia.py"
    click MULTIGAIA "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/run_multiple_gaia.sh"
    click CTRL_IF "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/controller/controller_interface.py"
    click NEO_DIRECT "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/controller/neo4j/directRetrieve/controller.py"
    click NEO_QUERY "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/controller/neo4j/queryRetrieve/controller.py"
    click NX_DIRECT "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/controller/networkX/directRetrieve/controller.py"
    click NX_QUERY "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/controller/networkX/queryRetrieve/controller.py"
    click KG_IF "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/knowledge_graph/kg_interface.py"
    click NEO_BACKEND "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/knowledge_graph/neo4j/main.py"
    click NX_BACKEND "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/knowledge_graph/networkX/main.py"
    click TOOL_IF "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/tools/tool_manager_interface.py"
    click PY_CODE "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/tools/PythonCodeTool.py"
    click TV2_IF "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/tools/tools_v2_3/tool_manager.py"
    click LLM "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/kgot/config_llms.json"
    click GAIA_FETCH "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/GAIA/dataset/fetch_gaia_dataset.py"
    click GAIA_BASE "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/GAIA/baselines/zero_shot.py"
    click GAIA_SCORE "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/GAIA/scorer.py"
    click PLOT_ANSWER "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/GAIA/plotters/answer_plot.py"
    click PLOT_COST "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/GAIA/plotters/cost_plot.py"
    click PLOT_LEADER "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/GAIA/plotters/leaderboard_plot.py"
    click DC_NEO "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/docker_instances/neo4j_docker/docker-compose.yaml"
    click DC_PYTOOL "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/docker_instances/python_docker/files/python_executor.py"
    click DC_KGOT "https://github.com/spcl/knowledge-graph-of-thoughts/tree/main/docker_instances/kgot_docker/"
    click VIS_BACK "https://github.com/spcl/knowledge-graph-of-thoughts/blob/main/snapshots_visualization_tool/backend/src/api.py"
    click VIS_FRONT "https://github.com/spcl/knowledge-graph-of-thoughts/tree/main/snapshots_visualization_tool/frontend/src/app/"

    %% Styles
    classDef orchestration fill:#AED6F1,stroke:#2E86C1,color:#1B4F72
    classDef datastore fill:#ABEBC6,stroke:#27AE60,color:#1D8348
    classDef external fill:#FAD7A0,stroke:#EB984E,color:#B9770E
    classDef ui fill:#D7BDE2,stroke:#8E44AD,color:#5B2C6F
    classDef eval fill:#E5E7E9,stroke:#A6ACAF,color:#566573
```
