# epistasislab/escargot architecture

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

- Interactive diagram: https://gitdiagram.com/epistasislab/escargot
- Repository: https://github.com/epistasislab/escargot

## Overview

##### Project Type and Purpose
- ESCARGOT is an open-source Python library (pip package) that orchestrates Large Language Models (LLMs) with a dynamic Graph of Thoughts (GoT) and knowledge graphs.
- Its goal is to improve accuracy and reduce hallucinations by combining:
- Strategic planning and code execution (Python-executable GoT)
- Structured Cypher queries against graph databases (Memgraph, Neo4j)
- Vector similarity backups (Weaviate, embeddings)
- Self-debugging capabilities

##### High-Level Architecture – Main Components
a. Client / Application Layer
– Your code or CLI that calls `Escargot.ask(...)`
b. Escargot Core API
– Entry point (`escargot/escargot.py`)
– Configuration loader (`agents/config.py`, `escargot/language_models/config_template.json`)
c. Controller & Workflow Manager
– `escargot/controller/controller.py`: orchestrates strategy generation, assessment, execution loop
– Multi-agent support (`escargot/multiagent/multiagent_manager.py`)
d. Graph of Thoughts Engine
– `escargot/operations/graph_of_operations.py` & `operations.py`: builds and traverses the dynamic GoT
– `escargot/parser/parser.py`: converts LLM output into structured GoT steps, code, XML
e. Language Model Interface
– Abstract interface (`escargot/language_models/abstract_language_model.py`)
– Concrete adapters: AzureGPT, ChatGPT, Ollama
f. Knowledge Retrieval Layer
– Cypher clients: Memgraph (`escargot/cypher/memgraph.py`), Neo4j
– Vector DB clients: Weaviate (`escargot/vector_db/weaviate.py`), Azure Embeddings
g. Execution & Self-Debugging
– Direct Python execution of generated code
– Self-debugging / error-handling in `escargot/operations/utils.py`
h. Memory & Caching
– `escargot/memory/memory.py`: caches intermediate results, prevents redundant calls
i. Benchmarking Harness (optional external component)
– `benchmarking/benchmarking.py`, datasets & notebooks: evaluates performance

##### Component Interactions and Data Flows
1. Client → Escargot Core: `ask(question, params)`
2. Core loads config → Controller
3. Controller issues planning prompt to LLM adapter → receives initial strategy
4. Parser converts strategy text → GoT graph nodes & edges
5. Controller traverses GoT: for each thought node
- If “query graph DB”: call Cypher client → return structured data
- Else if “vector search fallback”: call vector DB client → return similarities
- Else if “compute”: generate Python snippet via LLM → execute locally → gather output
- On error: self-debug loop (generate patch, re-execute)
6. Memory module caches each step’s results
7. Final answer assembled by Prompter (`prompter/prompter.py`) → returned to client

##### Architectural Patterns & Design Principles
- **Modular Adapters**: abstract interfaces for LLMs, graph DBs, vector DBs → easy to add new providers
- **Pipeline / Workflow Orchestration**: clear separation between planning, parsing, execution
- **Graph-of-Thoughts**: dynamic graph structure for reasoning, not linear prompt chain
- **Self-healing Execution**: automatic error detection & correction loop
- **Dependency Injection / Config-Driven**: all endpoints & credentials in a single config

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["Client Application"]:::external
    click Client "https://github.com/epistasislab/escargot/blob/main/escargot/escargot.py"

    subgraph "Escargot Core"
        class EscargotCore core
        ConfigLoader["Config Loader"]:::core
        click ConfigLoader "https://github.com/epistasislab/escargot/blob/main/agents/config.py"
        click ConfigLoader "https://github.com/epistasislab/escargot/blob/main/escargot/language_models/config_template.json"

        subgraph "Controller & Workflow"
            Controller["Controller"]:::core
            click Controller "https://github.com/epistasislab/escargot/blob/main/escargot/controller/controller.py"
            MultiAgent["Multi-Agent Manager"]:::core
            click MultiAgent "https://github.com/epistasislab/escargot/blob/main/escargot/multiagent/multiagent_manager.py"
        end

        subgraph "GoT & Parsing"
            Parser["Parser"]:::core
            click Parser "https://github.com/epistasislab/escargot/blob/main/escargot/parser/parser.py"
            GoTEngine["Graph of Thoughts Engine"]:::core
            click GoTEngine "https://github.com/epistasislab/escargot/blob/main/escargot/operations/graph_of_operations.py"
            click GoTEngine "https://github.com/epistasislab/escargot/blob/main/escargot/operations/operations.py"
        end

        subgraph "Execution & Memory"
            Executor["Execution & Self-Debug"]:::core
            click Executor "https://github.com/epistasislab/escargot/blob/main/escargot/operations/utils.py"
            CodeExec["Python Code Executor"]:::core
            click CodeExec "https://github.com/epistasislab/escargot/blob/main/escargot/coder/coder.py"
            Memory["Memory & Cache"]:::core
            click Memory "https://github.com/epistasislab/escargot/blob/main/escargot/memory/memory.py"
        end

        Prompter["Prompter"]:::core
        click Prompter "https://github.com/epistasislab/escargot/blob/main/escargot/prompter/prompter.py"
    end

    subgraph "LLM Adapters"
        AbstractLLM["Abstract LLM Interface"]:::abstract
        click AbstractLLM "https://github.com/epistasislab/escargot/blob/main/escargot/language_models/abstract_language_model.py"
        Azure["AzureGPT"]:::external
        click Azure "https://github.com/epistasislab/escargot/blob/main/escargot/language_models/azuregpt.py"
        ChatGPT["ChatGPT"]:::external
        click ChatGPT "https://github.com/epistasislab/escargot/blob/main/escargot/language_models/chatgpt.py"
        Ollama["Ollama"]:::external
        click Ollama "https://github.com/epistasislab/escargot/blob/main/escargot/language_models/ollama.py"
    end

    subgraph "Knowledge Layer"
        subgraph "Graph DB Clients"
            Memgraph[(Memgraph)]:::db
            click Memgraph "https://github.com/epistasislab/escargot/blob/main/escargot/cypher/memgraph.py"
            Neo4j[(Neo4j)]:::db
            click Neo4j "https://github.com/epistasislab/escargot/blob/main/escargot/cypher/neo4j.py"
        end
        subgraph "Vector DB Clients"
            Weaviate[(Weaviate)]:::db
            click Weaviate "https://github.com/epistasislab/escargot/blob/main/escargot/vector_db/weaviate.py"
            Embedding[(Azure Embeddings)]:::db
            click Embedding "https://github.com/epistasislab/escargot/blob/main/escargot/vector_db/azure_embedding.py"
        end
    end

    subgraph "Execution Environment"
        PythonRuntime["Python Runtime"]:::external
    end

    subgraph "Benchmarking Harness"
        Benchmark["Benchmarking Script"]:::external
        click Benchmark "https://github.com/epistasislab/escargot/blob/main/benchmarking/benchmarking.py"
        Dataset["Datasets"]:::external
        click Dataset "https://github.com/epistasislab/escargot/tree/main/benchmarking/dataset/"
        Notebooks["Notebooks"]:::external
        click Notebooks "https://github.com/epistasislab/escargot/tree/main/benchmarking/notebooks/"
    end

    Client -->|"ask()"| ConfigLoader
    ConfigLoader --> Controller
    Controller -->|"planning prompt"| AbstractLLM
    AbstractLLM --> Azure
    AbstractLLM --> ChatGPT
    AbstractLLM --> Ollama
    Azure -->|"strategy"| Controller
    ChatGPT -->|"strategy"| Controller
    Ollama -->|"strategy"| Controller
    Controller --> Parser
    Parser --> GoTEngine
    GoTEngine --> Executor
    Executor --> CodeExec
    CodeExec --> PythonRuntime
    Executor --> Memory
    GoTEngine -->|"cypher query"| Memgraph
    GoTEngine -->|"cypher query"| Neo4j
    GoTEngine -->|"fallback"| Weaviate
    GoTEngine -->|"fallback"| Embedding
    Executor -->|"error"| Executor
    Executor --> Memory
    Memory --> Controller
    Controller --> Prompter
    Prompter -->|"answer"| Client

    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px
    classDef abstract fill:#F9E79F,stroke:#B7950B,stroke-width:2px,stroke-dasharray:5 5
    classDef external fill:#ABEBC6,stroke:#196F3D,stroke-width:2px
    classDef db fill:#ABEBC6,stroke:#145A32,stroke-width:2px
```
