# idea-finai/tog-2 architecture

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

- Interactive diagram: https://gitdiagram.com/idea-finai/tog-2
- Repository: https://github.com/idea-finai/tog-2

## Overview

##### Project Type and Purpose
- This is a research‐oriented full‐stack Python application that performs knowledge‐guided, retrieval‐augmented LLM reasoning (Think‐on‐Graph 2.0).
- It consists of three logical layers:
a. Data and knowledge‐graph setup (Wikidata submodule + datasets)
b. Retrieval + reasoning pipeline (ToG-2 folder)
c. Evaluation suite (eval folder)

##### Top‐Level Components
- CLI Orchestrator (main_tog2.py)
- Named Entity Recognition (ner.py) via Azure API
- Retrieval Engine (search.py) using embedding models & BM25
- Graph Client (client.py + server_urls.txt) communicating with a local Wikidata HTTP service
- Prompt Library (prompt_list.py) for exploration & reasoning stages
- LLM Interface (OpenAI or local LLM calls within utils.py)
- Result Serializer (search.save_2_jsonl_simplier → JSONL output)
- Evaluation Script (eval/eval.py + utils.py) computing Exact Match
- Knowledge‐Graph Stack (Wikidata/simple_wikidata_db):
- Preprocessing stage (preprocess_dump.py + worker/writer/reader)
- Index building (db_deploy/build_index.py via shell scripts)
- Local HTTP server (db_deploy/server.py)

##### Relationships & Data Flow
a. User invokes main_tog2.py with CLI flags →
b. NER Module: sends text to Azure, tags entities →
c. Retrieval Module: for each entity/query, calls embedding/BM25 search →
d. Graph Client: for retrieval results, issues HTTP queries to the local Wikidata service →
e. Search Graph: builds exploration trees to given depth/width, prunes relations →
f. Prompt Generator: builds prompts from prompt_list.py →
g. LLM Module: sends prompts to OpenAI/gpt‐API or local LLM →
h. Aggregator: collects reasoning outputs, applies self-consistency threshold →
i. Serializer: writes predictions to JSONL →
j. Eval Script: consumes JSONL + ground‐truth data → calculates Exact Match.

##### Architectural Patterns & Key Technologies
- Modular pipeline: clear separation of concerns for NER, retrieval, graph search, prompting, LLM calls, and evaluation.
- Microservice for knowledge graph: local HTTP service exposing KG index.
- Asynchronous Preprocessing: reader, worker, writer processes for dump preprocessing.
- Shell‐scripted orchestration (`build_index.sh`, `start_server.sh`).
- Core libraries & frameworks: Python 3, OpenAI API, Azure Cognitive Services, embedding models (`bge`, `minilm`, `colbert`), BM25, JSON.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Preprocessing & KG Service
  subgraph "Preprocessing & KG Service"
    direction TB
    PD["Preprocess Dump\npreprocess_dump.py"]:::internal
    PR["Reader Process\nreader_process.py"]:::internal
    PW["Worker Process\nworker_process.py"]:::internal
    PW2["Writer Process\nwriter_process.py"]:::internal
    BI_SH["Build Index Script\nbuild_index.sh"]:::internal
    BI["Index Builder\nbuild_index.py"]:::internal
    SS_SH["Start Server Script\nstart_server.sh"]:::internal
    SV["KG HTTP Server\nserver.py"]:::service
    KC["KG Client\nclient.py"]:::internal
    DU["DB Deploy Utils\nutils.py"]:::internal
    GU["KG Utilities\nutils.py"]:::internal
    click PD "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/preprocess_dump.py"
    click PR "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/preprocess_utils/reader_process.py"
    click PW "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/preprocess_utils/worker_process.py"
    click PW2 "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/preprocess_utils/writer_process.py"
    click BI_SH "https://github.com/idea-finai/tog-2/blob/main/Wikidata/scripts/build_index.sh"
    click BI "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/db_deploy/build_index.py"
    click SS_SH "https://github.com/idea-finai/tog-2/blob/main/Wikidata/scripts/start_server.sh"
    click SV "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/db_deploy/server.py"
    click KC "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/db_deploy/client.py"
    click DU "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/db_deploy/utils.py"
    click GU "https://github.com/idea-finai/tog-2/blob/main/Wikidata/simple_wikidata_db/utils.py"
    PD --> PR --> PW --> PW2 --> BI_SH --> BI --> SS_SH --> SV
  end

  %% Main Pipeline
  subgraph "Main Pipeline"
    direction TB
    CLI["CLI Orchestrator\nmain_tog2.py"]:::internal
    NER["NER Module\nner.py"]:::internal
    AZURE["Azure NER Service"]:::external
    RET["Retrieval Engine\nsearch.py"]:::internal
    GC["Graph Client\nclient.py"]:::internal
    KG_SVC["Local KG HTTP Service"]:::service
    GS["Graph Search & Pruning"]:::internal
    PL["Prompt Library\nprompt_list.py"]:::internal
    LLM["LLM Interface\nutils.py"]:::internal
    OPENAI["OpenAI / Local LLM"]:::external
    SER["Result Serializer\n(save_2_jsonl_simplier)"]:::internal
    DATA_OUT["Output JSONL"]:::datastore

    click CLI "https://github.com/idea-finai/tog-2/blob/main/ToG-2/main_tog2.py"
    click NER "https://github.com/idea-finai/tog-2/blob/main/ToG-2/ner.py"
    click RET "https://github.com/idea-finai/tog-2/blob/main/ToG-2/search.py"
    click GC "https://github.com/idea-finai/tog-2/blob/main/ToG-2/client.py"
    click PL "https://github.com/idea-finai/tog-2/blob/main/ToG-2/prompt_list.py"
    click LLM "https://github.com/idea-finai/tog-2/blob/main/ToG-2/utils.py"
    click SER "https://github.com/idea-finai/tog-2/blob/main/ToG-2/search.py"

    CLI -->|"invokes CLI flags"| NER
    NER -->|"annotated text"| RET
    NER --> AZURE
    RET -->|"entity queries"| GC
    GC -->|"HTTP GET entity facts"| KG_SVC
    KG_SVC --> SV
    GC -->|"facts data"| GS
    GS -->|"exploration trees"| PL
    PL -->|"prompts"| LLM
    LLM -->|"LLM prompt"| OPENAI
    OPENAI -->|"LLM response"| LLM
    LLM -->|"reasoning outputs"| SER
    SER -->|"writes JSONL"| DATA_OUT
  end

  %% Evaluation
  subgraph "Evaluation"
    direction TB
    EVAL["Eval Script\neval.py"]:::internal
    EU["Eval Utils\nutils.py"]:::internal
    DATA_IN["Data Store\ndata/"]:::datastore
    JSONL["Predictions JSONL"]:::datastore

    click EVAL "https://github.com/idea-finai/tog-2/blob/main/eval/eval.py"
    click EU "https://github.com/idea-finai/tog-2/blob/main/eval/utils.py"
    click DATA_IN "https://github.com/idea-finai/tog-2/tree/main/data/"

    DATA_IN --> EVAL
    JSONL --> EVAL
    EVAL -->|"Exact Match results"| EU
  end

  %% Legend
  subgraph Legend
    direction TB
    A["Python Module"]:::internal
    B["External Service"]:::external
    C["Data Store / File"]:::datastore
    D["Long‐Running Service"]:::service
  end

  classDef internal fill:#bbf,stroke:#333,stroke-width:1px
  classDef external fill:#bfb,stroke:#333,stroke-width:1px
  classDef datastore fill:#f96,stroke:#333,stroke-width:1px
  classDef service fill:#6f6,stroke:#333,stroke-width:1px
```
