# wannabeasmartguy/gpt-gradio-agent architecture

> Architecture diagram of the GitHub repository wannabeasmartguy/gpt-gradio-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wannabeasmartguy/gpt-gradio-agent
- Repository: https://github.com/wannabeasmartguy/gpt-gradio-agent

## Overview

##### Project type and purpose
- This is a Python-based, full-stack desktop/web application built on Gradio that provides:
- A chatbox interface to interact with GPT (Azure or OpenAI) or a local LLM (Ollama)
- A GPT-driven, RAG-capable knowledge-base management module (CRUD + embedding + retrieval + reranking)
- DALL·E-3 image generation via Azure OpenAI
- Bing-powered web search integration with history tracking

##### File structure
- Top-level entrypoint: GPT-Gradio-Agent.py launches the Gradio UI
- “Agent/” folder: core agent logic (agent.py, agent_tools.py)
- “vecstore/” folder: vector store implementation (embedding, searching, reranking, templating)
- “embedding model/”: placeholder for local Hugging Face embedding models
- “local_llm/ollama.py”: adapter to run a local LLM via Ollama
- “pic_gen/”: DALL·E-3 image generation logic
- “search_his/”: persistence for RAG search history
- “knowledge base/”: storage for user’s document collections
- “gga_utils/”, “text_splitter/”, “style/”, “locale/”: shared utilities, text-chunking, CSS styling, i18n

##### README for additional insights
- Gradio frontend binds to several “pages” or “tabs”: Chat, Knowledge Base, Image Gen, RAG Search
- Supports both cloud APIs (Azure OpenAI + Bing Search) and fully local LLM/embed pipelines

##### Main components
a. Frontend Layer (Gradio UI)
- Chat Tab
- Knowledge Base Manager Tab
- Image Generation Tab
- RAG Search Tab
b. Backend Layer (Python modules)
- ChatController (orchestrates Agent.agent.py + gga_utils + vecstore.search_engine)
- KBController (CRUD on “knowledge base/” files + embedding via vecstore.vecstore)
- ImageGenController (pic_gen.pic_gen.py → Azure DALL·E API)
- SearchController (search_his + vecstore.reranker + Bing Search API)
c. Data Layer
- Local file system: “knowledge base/”, “search_his/”
- Vector Store: persistent embeddings (vecstore/vecstore.py; stores index on disk)
d. External Services
- Azure OpenAI API (chat completions, embeddings, DALL·E-3)
- Bing Web Search API
- Optional Hugging Face local embedding model
- Optional Ollama local LLM

##### Relationships and interactions
- User → Gradio UI → appropriate Controller
- Controller ↔ Agent & vecstore modules for RAG workflows
- Controller → Azure OpenAI or local LLM for chat
- Controller → Azure OpenAI for DALL·E-3 image generation
- Controller → Bing Search API → reranker → UI
- Controller ↔ local files (KB CRUD & history persistence)

##### Architectural patterns & design principles
- Modular Monolith: separate folders for each concern (Chat, KB, Embedding, Search, Image Gen)
- RAG pipeline: Text splitter → Embed → Vector index → Retrieve → Rerank → LLM prompt
- Adapter pattern: local_llm/ollama.py abstracts LLM backend; embedding_model folder abstracts HF models

4. Inside Backend layer, group modules by function:
– ChatController → Agent.agent.py → gga_utils
– KBController → text_splitter → vecstore.vecstore/search_engine
– ImageGenController → pic_gen.pic_gen.py
– SearchController → search_his + vecstore.reranker → Bing Search

##### Final reminder
- Be very detailed: capture each module folder as a component

This structure will give stakeholders and new team members an accurate, high-level overview of how GPT-Gradio-Agent is organized and how its pieces interact end-to-end.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        User(["User"]):::external
        GPTUI["Gradio UI"]:::frontend
        ChatTab["Chat Tab"]:::frontend
        KBTab["Knowledge Base Tab"]:::frontend
        ImgTab["Image Generation Tab"]:::frontend
        RAGTab["RAG Search Tab"]:::frontend
        Styling["style.css"]:::frontend
        LocaleEN["en_US.json"]:::frontend
        LocaleCN["zh_CN.json"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        ChatController["ChatController"]:::backend
        AgentModule["Agent\n(agent.py)"]:::backend
        AgentTools["Agent Tools\n(agent_tools.py)"]:::backend

        KBController["KBController"]:::backend
        TextSplitter["Text Splitter\n(chinese_text_splitter.py)"]:::backend
        VecstoreCore["Vecstore Core\n(vecstore.py)"]:::backend
        SearchEngine["Search Engine\n(search_engine.py)"]:::backend
        TemplateMod["Template\n(template.py)"]:::backend

        ImageGenController["ImageGenController"]:::backend

        SearchController["SearchController"]:::backend
        Reranker["Reranker\n(reranker.py)"]:::backend

        Common["common.py"]:::backend
        Theme["theme.py"]:::backend
        VecUtils["vec_utils.py"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        KnowledgeBaseFS(("Knowledge Base FS")):::data
        VectorStore(("Vector Store")):::data
        SearchHistoryFS(("Search History FS")):::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AzureOpenAI(["Azure OpenAI API"]):::external
        BingSearch(["Bing Search API"]):::external
        HFAdapter(["HF Embed Model"]):::external
        LocalLLM(["Ollama LLM"]):::external
    end

    %% Relationships
    User -->|uses| GPTUI
    GPTUI -->|selects| ChatTab
    GPTUI -->|selects| KBTab
    GPTUI -->|selects| ImgTab
    GPTUI -->|selects| RAGTab
    GPTUI -->|loads| Styling
    GPTUI -->|loads| LocaleEN
    GPTUI -->|loads| LocaleCN

    ChatTab -->|invoke| ChatController
    ChatController -->|calls| AgentModule
    ChatController -->|calls| AgentTools
    ChatController -->|calls| AzureOpenAI
    ChatController -->|calls| LocalLLM
    ChatController -->|uses| Common
    ChatController -->|uses| VecUtils

    KBTab -->|invoke| KBController
    KBController -->|uses| TextSplitter
    KBController -->|writes/read| KnowledgeBaseFS
    KBController -->|calls| VecstoreCore
    KBController -->|calls| SearchEngine
    KBController -->|calls| TemplateMod
    KBController -->|uses| Common

    ImgTab -->|invoke| ImageGenController
    ImageGenController -->|REST API| AzureOpenAI

    RAGTab -->|invoke| SearchController
    SearchController -->|reads/writes| SearchHistoryFS
    SearchController -->|calls| Reranker
    SearchController -->|calls| BingSearch
    SearchController -->|calls| SearchEngine
    SearchController -->|uses| Common

    %% Data connections
    VecstoreCore -->|stores| VectorStore
    SearchEngine -->|indexes| VectorStore
    Reranker -->|reranks with| VectorStore

    %% Optional local services
    HFAdapter -->|provides| VecstoreCore
    LocalLLM -->|provides| AgentModule

    %% Click Events
    click GPTUI "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/GPT-Gradio-Agent.py"
    click AgentModule "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/Agent/agent.py"
    click AgentTools "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/Agent/agent_tools.py"
    click KBController "https://github.com/wannabeasmartguy/gpt-gradio-agent/tree/main/knowledge base/"
    click VecstoreCore "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/vecstore/vecstore.py"
    click TextSplitter "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/text_splitter/chinese_text_splitter.py"
    click SearchEngine "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/vecstore/search_engine.py"
    click TemplateMod "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/vecstore/template.py"
    click ImageGenController "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/pic_gen/pic_gen.py"
    click SearchController "https://github.com/wannabeasmartguy/gpt-gradio-agent/tree/main/search_his/"
    click Reranker "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/vecstore/reranker.py"
    click Common "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/gga_utils/common.py"
    click Theme "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/gga_utils/theme.py"
    click VecUtils "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/gga_utils/vec_utils.py"
    click Styling "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/style/style.css"
    click LocaleEN "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/locale/en_US.json"
    click LocaleCN "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/locale/zh_CN.json"
    click HFAdapter "https://github.com/wannabeasmartguy/gpt-gradio-agent/tree/main/embedding model/"
    click LocalLLM "https://github.com/wannabeasmartguy/gpt-gradio-agent/blob/main/local_llm/ollama.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#005B9F,color:#000;
    classDef backend fill:#DFF5D8,stroke:#1F7A1F,color:#000;
    classDef data fill:#FFE4B2,stroke:#B36B00,color:#000;
    classDef external fill:#E0E0E0,stroke:#666,color:#000
```
