# quangbk/generativeagent_llm architecture

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

- Interactive diagram: https://gitdiagram.com/quangbk/generativeagent_llm
- Repository: https://github.com/quangbk/generativeagent_llm

## Overview

##### Main Components
- Notebook Interface: Represent the main_agent.ipynb file as the entry point used by users or researchers to experiment with the generative agent workflow.
- Server Module:
- Generative Agent Component: This is primarily implemented in server/generativeAgent.py. It orchestrates the agent’s behavior (memory, planning, reaction, dialogue generation, and interviews).
- Model and Prompt Handling: server/model.py and server/prompt.py are likely responsible for setting up the LLM model’s parameters and preparing input prompts.
- Memory Retrieval: server/time_weighted_retriever.py handles the memory querying based on temporal weighting. This module plays a vital role in the “memory” aspect mentioned in the features.
- GPTQ Module: Under server/gptq, include:
- gptq.py, modelutils.py, and quant.py as components that interface and manage the local LLM inference with quantization methods — they provide lower-level access and optimizations for the language model used by the agent.

##### Relationships and Interactions
- The Notebook (main_agent.ipynb) acts as the client/driver that creates and interacts with a GenerativeAgent instance.
- The GenerativeAgent (in server/generativeAgent.py) uses:
- Guidance and Langchain (external libraries) to generate dialogues, summaries, reaction, planning, and more.
- The model and prompt components to construct the query/input for the LLM.
- The memory module (time_weighted_retriever.py) to fetch relevant memories during interactions.
- The GPTQ module for efficient LLM inference and any model quantization operations.

##### Architectural Patterns and Design Principles
- Modularity: The separation between agent logic (generativeAgent.py), memory retrieval, and low-level model operations (GPTQ folder) demonstrates a modular design.
- Separation of Concerns: Different responsibilities (e.g., generating dialogue, memory management, LLM interfacing) are clearly split into separate modules – this is a key design principle.
- External Integration: The architecture integrates external dependencies like Guidance, Langchain, and Faiss for vector memory handling, so these should be noted where the agent’s logic calls into these libraries.

##### Relevant Technologies, Frameworks, and Libraries
- Guidance (for prompt guidance and LLM query construction).
- Langchain (for managing agent simulation routines).
- Faiss (as an example vector store used for memory and retrieval, although it may be swapped with alternatives).
- GPTQ-for-LLaMa (as the engine to run local LLMs with quantization).

b. Inside, start with the Notebook Interface at the top or left as the entry point.
- The Generative Agent module.
- Within or attached to it, include Administrator sub-components for Prompt/Model generation and Memory Retrieval.
d. To the side (or as a connected module), illustrate the GPTQ block containing its files (gptq.py, modelutils.py, quant.py) that feed into the Generative Agent.
- The Notebook calls the Generative Agent.
- The Agent uses the Prompt/Model and Memory Retriever.
- The Agent calls the GPTQ module for LLM-related operations.
- External libraries (Guidance, Langchain, Faiss) interact with the Agent and Memory Retriever.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Generative Agent System"
        Notebook["Notebook Interface"]
        subgraph "Server Module"
            GA["Generative Agent"]
            MH["Model Handler"]
            PH["Prompt Handler"]
            MR["Memory Retriever"]
        end
        subgraph "GPTQ Module"
            GPTQ1["gptq.py"]
            GPTQ2["Model Utilities"]
            GPTQ3["Quantization Utilities"]
        end
        subgraph "External Libraries"
            GUID["Guidance Library"]
            LANG["Langchain Library"]
            FAIS["Faiss (Vector Store)"]
        end
    end

    Notebook -->|"invokesAgentFunctions"| GA
    GA -->|"callsModelHandler"| MH
    GA -->|"callsPromptHandler"| PH
    GA -->|"queriesMemoryRetriever"| MR
    GA -->|"invokesGPTQ"| GPTQ1
    MR -->|"retrievesVia"| FAIS
    GA -->|"integratesWith"| GUID
    GA -->|"integratesWith"| LANG

    GPTQ1 -->|"usesUtilitiesFrom"| GPTQ2
    GPTQ1 -->|"usesUtilitiesFrom"| GPTQ3

    click Notebook "https://github.com/quangbk/generativeagent_llm/blob/main/main_agent.ipynb"
    click GA "https://github.com/quangbk/generativeagent_llm/blob/main/server/generativeAgent.py"
    click MH "https://github.com/quangbk/generativeagent_llm/blob/main/server/model.py"
    click PH "https://github.com/quangbk/generativeagent_llm/blob/main/server/prompt.py"
    click MR "https://github.com/quangbk/generativeagent_llm/blob/main/server/time_weighted_retriever.py"
    click GPTQ1 "https://github.com/quangbk/generativeagent_llm/blob/main/server/gptq/gptq.py"
    click GPTQ2 "https://github.com/quangbk/generativeagent_llm/blob/main/server/gptq/modelutils.py"
    click GPTQ3 "https://github.com/quangbk/generativeagent_llm/blob/main/server/gptq/quant.py"

    classDef client fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef server fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef gptq fill:#ffa07a,stroke:#333,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:2px;

    class Notebook client;
    class GA,MH,PH,MR server;
    class GPTQ1,GPTQ2,GPTQ3 gptq;
    class GUID,LANG,FAIS external;
```
