# xmzhangai/metamind architecture

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

- Interactive diagram: https://gitdiagram.com/xmzhangai/metamind
- Repository: https://github.com/xmzhangai/metamind

## Overview

##### Project Type and Purpose
- MetaMind is a full-stack Python application providing both a command-line interface (CLI) and a Flask-based web interface for orchestrating a multi-agent social reasoning pipeline atop Large Language Models (LLMs).
- Its core purpose is to simulate human-like metacognitive processes (Theory-of-Mind, domain reasoning, response validation) by chaining three specialized agents (ToM Agent, Domain Agent, Response Agent) and a dynamic social memory.

##### File-Tree-Based Structural Analysis
- Top-Level Components:
- agents/ – core agent implementations (base_agent.py, tom_agent.py, domain_agent.py, response_agent.py)
- llm_interface/ – abstraction over LLM backends (base_llm.py, openai_llm.py)
- memory/ – social_memory.py for storing and updating long-term user patterns
- prompts/ – prompt_templates.py for standardized prompt construction
- utils/ – helpers.py for shared utilities
- config.py – central configuration (API keys, model settings, agent hyperparameters)
- main.py – CLI entrypoint
- app.py – Flask web server launching templates/index.html + static assets
- templates/ & static/ – front-end resources (Jinja2 templates, JS, CSS)
- evaluations/ & sample_cases_0508/ – benchmark scripts and JSON test cases
- Architectural Choices:
- Layered separation: Presentation (CLI/Web), Orchestration, Agent Pipeline (ToM → Domain → Response), Integration (LLM calls), Persistence (Social Memory), Configuration.
- Modular design encourages swapping LLM backends or agent parameters via config.py.

##### Key README Insights
- Three-stage cognitive pipeline:
1. Theory-of-Mind (hypothesis generation)
2. Domain Agent (refinement & scoring)
3. Response Agent (generation + validation + memory update)
- Social Memory: evolving store of user patterns, decays over time, informs all stages.
- Evaluations (ToMBench, STSS) are external scripts calling the same pipeline.

- Frontend:
- CLI Module (main.py)
- Web Server (app.py + templates/index.html + static/js/css)
- Orchestrator/Core Logic:
- Input Processor (parses user query, selects persona/context)
- Agent Pipeline:
· ToM Agent
· Domain Agent
· Response Agent
- Social Memory Store
- Prompt Manager (templates)
- Config Loader
- Integration Layer:
- LLM Interface (base_llm → openai_llm)
- External LLM API (OpenAI or custom endpoint)
- Evaluation Suite:
- ToMBench Runner (eval_tombench.py)
- Sample Cases Loader
1. User → (CLI/Web UI) → Orchestrator
2. Orchestrator uses Config + Prompt Manager to build prompt → passes to ToM Agent
3. ToM Agent → calls LLM Interface → External LLM API → receives raw output → yields hypotheses
4. Hypotheses + Social Memory → Domain Agent → refines & scores → selects top hypothesis
5. Selected hypothesis + Social Memory → Response Agent → generates & validates final response
6. Response Agent updates Social Memory → Orchestrator returns response to UI → User
7. Evaluation Suite injects sample interactions into the same pipeline and records metrics
c. Architectural Patterns & Principles:
- Pipeline Pattern: sequential agent stages transform data
- Dependency Inversion: LLM calls abstracted behind base_llm interface
- Single Responsibility: each agent module focuses on one cognitive function
- Config-driven Behavior: hyperparameters and API settings centralized in config.py
d. Technologies & Frameworks:
- Python 3.x, Flask (app.py), Jinja2 (templates), JavaScript/CSS (static assets)
- OpenAI (or custom) API via llm_interface/openai_llm.py
- JSON-based social memory and sample cases

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLI["CLI Module\n(main.py)"]:::frontend
        WebServer["Web Server\n(app.py)"]:::frontend
        Templates["Templates\n(index.html)"]:::frontend
        StaticJS["Static JS\n(script.js)"]:::frontend
        StaticCSS["Static CSS\n(style.css)"]:::frontend
    end

    CLI -->|user input| InputProc
    WebServer -->|HTTP request| InputProc
    WebServer --> Templates
    WebServer --> StaticJS
    WebServer --> StaticCSS

    %% Orchestration & Core Logic Layer
    subgraph "Orchestration Layer"
        direction TB
        InputProc["Input Processor"]:::core
        ConfigLoader["Config Loader\n(config.py)"]:::config
        PromptManager["Prompt Manager\n(prompt_templates.py)"]:::core
        Helpers["Utility Helpers\n(helpers.py)"]:::core

        subgraph "Agent Pipeline" 
            direction TB
            ToMAgent["ToM Agent\n(tom_agent.py)"]:::core
            DomainAgent["Domain Agent\n(domain_agent.py)"]:::core
            ResponseAgent["Response Agent\n(response_agent.py)"]:::core
            BaseAgent["Base Agent\n(base_agent.py)"]:::core
        end

        SocialMem["Social Memory Store\n(social_memory.py)"]:::core
    end

    InputProc -->|loads| ConfigLoader
    InputProc -->|constructs prompt| PromptManager
    InputProc -->|calls| ToMAgent

    %% Agent Pipeline Flows
    ToMAgent -->|prompt text| LLMInterfaceBase
    LLMInterfaceBase -->|API request| OpenAILLM
    OpenAILLM -->|HTTP call| ExternalAPI["External LLM API"]:::integration
    ExternalAPI -->|raw output| OpenAILLM
    OpenAILLM -->|response| LLMInterfaceBase
    LLMInterfaceBase -->|hypotheses| ToMAgent
    ToMAgent -->|hypotheses list| DomainAgent
    DomainAgent -->|uses memory| SocialMem
    DomainAgent -->|top hypothesis| ResponseAgent
    ResponseAgent -->|validation| SocialMem
    ResponseAgent -->|final response| InputProc
    InputProc -->|deliver response| CLI
    InputProc -->|deliver response| WebServer

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        LLMInterfaceBase["LLM Interface Base\n(base_llm.py)"]:::integration
        OpenAILLM["OpenAI LLM\n(openai_llm.py)"]:::integration
        ExternalAPI
    end

    %% Evaluation Suite
    subgraph "Evaluation Suite" 
        direction TB
        EvalRunner["ToMBench Runner\n(eval_tombench.py)"]:::config
        SampleCases["Sample Cases\n(JSON Store)"]:::config
    end

    EvalRunner -->|injects cases| InputProc
    SampleCases --> EvalRunner

    %% Click Events
    click CLI "https://github.com/xmzhangai/metamind/blob/main/main.py"
    click WebServer "https://github.com/xmzhangai/metamind/blob/main/app.py"
    click Templates "https://github.com/xmzhangai/metamind/blob/main/templates/index.html"
    click StaticJS "https://github.com/xmzhangai/metamind/blob/main/static/script.js"
    click StaticCSS "https://github.com/xmzhangai/metamind/blob/main/static/style.css"
    click ConfigLoader "https://github.com/xmzhangai/metamind/blob/main/config.py"
    click ToMAgent "https://github.com/xmzhangai/metamind/blob/main/agents/tom_agent.py"
    click DomainAgent "https://github.com/xmzhangai/metamind/blob/main/agents/domain_agent.py"
    click ResponseAgent "https://github.com/xmzhangai/metamind/blob/main/agents/response_agent.py"
    click BaseAgent "https://github.com/xmzhangai/metamind/blob/main/agents/base_agent.py"
    click LLMInterfaceBase "https://github.com/xmzhangai/metamind/blob/main/llm_interface/base_llm.py"
    click OpenAILLM "https://github.com/xmzhangai/metamind/blob/main/llm_interface/openai_llm.py"
    click SocialMem "https://github.com/xmzhangai/metamind/blob/main/memory/social_memory.py"
    click PromptManager "https://github.com/xmzhangai/metamind/blob/main/prompts/prompt_templates.py"
    click Helpers "https://github.com/xmzhangai/metamind/blob/main/utils/helpers.py"
    click EvalRunner "https://github.com/xmzhangai/metamind/blob/main/evaluations/tombench/eval_tombench.py"
    click SampleCases "https://github.com/xmzhangai/metamind/tree/main/sample_cases_0508/"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef core fill:#E8F5E9,stroke:#2E7D32,color:#000
    classDef integration fill:#FFF3E0,stroke:#F57C00,color:#000
    classDef config fill:#ECEFF1,stroke:#455A64,color:#000
```
