How xmzhangai/metamind works
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