# neo4j-graphacademy/llm-chatbot-python architecture

> Architecture diagram of the GitHub repository neo4j-graphacademy/llm-chatbot-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neo4j-graphacademy/llm-chatbot-python
- Repository: https://github.com/neo4j-graphacademy/llm-chatbot-python

## Overview

##### Project type and purpose
- This is a single-page, full-stack Python application built on Streamlit that implements an LLM-driven chatbot over a Neo4j graph database.
- Core functionality: accept natural-language queries via the UI, orchestrate calls to an LLM and to Neo4j tools (vector search, Cypher queries), then display answers.

##### File structure
Top-level files and folders:
- .devcontainer / .streamlit: development and secrets config for Codespaces and Streamlit.
- bot.py: the Streamlit entry point (UI + request routing).
- agent.py: high-level orchestration of tools (LLM, graph, vector, Cypher).
- llm.py / graph.py: wrappers around LLM API and Neo4j graph operations.
- tools/: implementations of specific “tool” plugins (cypher.py, vector.py).
- examples/ and solutions/: sample code and test suite illustrating tool usage and expected behavior.
- requirements.txt: Python dependencies (Streamlit, neo4j-driver, openai, etc.).

##### README for additional insights
- The application runs as `streamlit run bot.py` on localhost:8501.
- A Neo4j instance with the “recommendations” dataset plus an embedding index is required.
- Tests exercise the agents and tools via pytest.

1) User Interface (Streamlit front-end in bot.py)
2) Chatbot Orchestrator (agent.py)
3) Tooling Layer:
– LLM Tool (llm.py wrapping OpenAI or other LLM API)
– Graph Tool (graph.py + tools/cypher.py for Cypher queries)
– Vector Tool (tools/vector.py for embedding lookups)
4) Data Store (Neo4j graph database)
5) External Service (OpenAI API endpoint)
- User → Streamlit UI
- UI → Orchestrator (calls to agent.run or similar)
- Orchestrator → LLM Tool (for natural-language understanding or generation)
- Orchestrator → Graph Tool (for direct Cypher)
- Orchestrator → Vector Tool (for semantic search)
- Graph/Vector Tools → Neo4j
- LLM Tool → OpenAI API
- Tools return results → Orchestrator → UI → User
c. Architectural patterns and design principles:
– Layered architecture (UI / orchestration / tools / data).
– Plugin-style tool registry: agent dynamically loads tools from tools/*.py.
– Single-process, modular Python codebase.
– Separation of concerns: API wrappers (graph.py, llm.py), tool implementations, orchestration.
d. Key technologies and libraries:
– Streamlit (web UI)
– neo4j-python-driver (graph connectivity)
– OpenAI (LLM)
– pytest (testing)
– Python 3.x

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "User Layer"
        direction TB
        User["User"]:::external
        UI["Streamlit UI"]:::front
    end

    subgraph "Application Layer"
        direction TB
        Agent["Agent Orchestrator"]:::orchestrator
    end

    subgraph "Tooling Layer"
        direction TB
        LLM["LLM Tool"]:::tool
        Graph["Graph Tool"]:::tool
        subgraph "Neo4j Integration"
            direction TB
            Cypher["Cypher Tool"]:::tool
            Vector["Vector Tool"]:::tool
        end
    end

    subgraph "Data Layer"
        direction TB
        Neo4j["Neo4j Graph DB"]:::db
    end

    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
    end

    subgraph "Configuration & Utilities"
        direction TB
        Secrets[".streamlit Secrets"]:::config
        DevContainer[".devcontainer"]:::config
        Utils["Utility Functions"]:::util
        Examples["Example Applications"]:::misc
        Tests["Sample Solutions & Tests"]:::misc
    end

    %% Connections
    User -->|"interacts with"| UI
    UI -->|"streamlit run bot.py"| Agent
    Agent -->|"uses"| LLM
    Agent -->|"uses"| Graph
    Agent -->|"uses"| Vector
    Graph -->|"Bolt / Cypher"| Cypher
    Cypher -->|"executes query"| Neo4j
    Vector -->|"vector lookup"| Neo4j
    LLM -->|"REST API"| OpenAI

    %% Results flow
    Neo4j -->|"query results"| Agent
    OpenAI -->|"LLM response"| Agent
    Agent -->|"renders response"| UI

    %% Click Events
    click UI "https://github.com/neo4j-graphacademy/llm-chatbot-python/blob/main/bot.py"
    click Agent "https://github.com/neo4j-graphacademy/llm-chatbot-python/blob/main/agent.py"
    click LLM "https://github.com/neo4j-graphacademy/llm-chatbot-python/blob/main/llm.py"
    click Graph "https://github.com/neo4j-graphacademy/llm-chatbot-python/blob/main/graph.py"
    click Cypher "https://github.com/neo4j-graphacademy/llm-chatbot-python/blob/main/tools/cypher.py"
    click Vector "https://github.com/neo4j-graphacademy/llm-chatbot-python/blob/main/tools/vector.py"
    click Secrets "https://github.com/neo4j-graphacademy/llm-chatbot-python/blob/main/.streamlit/secrets.toml.example"
    click DevContainer "https://github.com/neo4j-graphacademy/llm-chatbot-python/tree/main/.devcontainer/"
    click Utils "https://github.com/neo4j-graphacademy/llm-chatbot-python/blob/main/utils.py"
    click Examples "https://github.com/neo4j-graphacademy/llm-chatbot-python/tree/main/examples/"
    click Tests "https://github.com/neo4j-graphacademy/llm-chatbot-python/tree/main/solutions/"

    %% Styles
    classDef front fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef orchestrator fill:#DFFFD0,stroke:#36a64f,color:#36a64f;
    classDef tool fill:#FFF5CC,stroke:#e08e00,color:#e08e00;
    classDef db fill:#FFE5D9,stroke:#d1495b,color:#d1495b,shape:cylinder;
    classDef external fill:#FFE0E0,stroke:#d61a1a,color:#d61a1a;
    classDef config fill:#F0F0F0,stroke:#999999,color:#333333;
    classDef util fill:#E8F4FF,stroke:#1f78b4,color:#1f78b4;
    classDef misc fill:#F4F4F4,stroke:#666666,color:#333333;
```
