# marketagents-ai/marketagents architecture

> Architecture diagram of the GitHub repository marketagents-ai/marketagents, 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/marketagents-ai/marketagents
- Repository: https://github.com/marketagents-ai/marketagents

## Overview

##### Main Components
- Base agents (agent.py, prompter.py)
- Specialized agents (market_agent.py, market_agent_prompter.py)
- Persona definitions and weighted personas (covering different roles like Analyst, Investor, Trader, etc.)
- Cognitive tools, schemas, and steps which hint at the internal reasoning processes.
- Database Services: Under market_agents/agents/db, there are Dockerfiles, setup scripts, and dashboard code. This suggests a dedicated database service and UI dashboard component to manage prompt caching, agent storage, or simulation data.
- Orchestrators: In market_agents/orchestrators, components coordinate agent interactions, group chats, logging, and integration between agents and economic/environment modules.
- Memory: The market_agents/memory directory shows various modules for agent memory management, embedding, and a knowledge base. This forms the stateful storage and retrieval subsystem.
- Environments: The market_agents/environments folder and its “mechanisms” directory include economic simulations (auction, stock market, crypto, etc.) that define market conditions and external stimuli in the simulation.
- Inference: Two inference-related folders exist:
- market_agents/inference: Manages parallel inference, message models, and client integration with LLMs.
- minference: Likely a lighter or alternative inference engine with similar responsibilities.
- Economic Models: The market_agents/economics directory includes modules like econ_agent and econ_models that handle economic logic.
- Verbal RL: The market_agents/verbal_rl modules are focused on reinforcement learning aspects via natural language (e.g., reward model definitions).

##### Relationships and Interactions
- The Agents component is core and interacts with nearly every other module:
- It calls on the Memory and Inference services to perform essential functions (i.e., prompt processing, parallel inference).
- The Orchestrators coordinate between agents, group communications, and integration with the simulation environment.
- The Economics and Environments modules provide external market stimuli which agents react to.
- The Database Services act as the persistence layer for agent storage, prompt caching, and possibly simulation state:
- There is a two-way communication between the database layer and agent/memory components.
- The Inference modules interface with external LLM providers (as suggested by large language model prompts and parallel inference) to deliver computational intelligence.
- The entire system is integrated and configured through YAML/ENV configuration files residing in different areas (e.g., orchestrator_config.yaml, .env) as well as startup scripts like run_simulation.sh and start_market_agents.sh.

##### Architectural Patterns or Design Principles
- Modularity: The code is clearly divided by functional domain (agents, environments, orchestrators, memory, inference, etc.) which supports separation of concerns.
- Extensibility: The many agent personas and configurable prompts (YAML files) indicate the system is designed to be highly customizable.
- Microservice-like Boundaries: Components such as the database service and inference services (coupled with Docker and docker-compose files) are isolated, suggesting containerization and service orchestration.
- Parallel Processing: The inclusion of modules for parallel inference and cognitive steps shows a design that supports concurrent execution.

##### Detailed Elements
- Each component labeled clearly with its purpose (e.g., “Agent Module: Defines cognitive processes” or “In-memory Knowledge Base: Caches agent knowledge”).
- External integrations (e.g., API keys setup in .env, external LLMs).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Configurations
    CFG["Configurations (.env, YAML)"]:::config

    %% Agents Subgraph
    subgraph "Agents"
        A1["Base Agents & Cognitive Tools\n(agent.py, prompter.py, cognitive_tools.py)"]:::agent
        A2["Market Agent\n(market_agent.py)"]:::agent
        A3["Market Agent Prompter\n(market_agent_prompter.py)"]:::agent
        A4["Personas"]:::agent
        A5["Weighted Personas"]:::agent
    end

    %% Orchestrators Subgraph
    subgraph "Orchestrators"
        O1["Base Orchestrator"]:::orch
        O2["Meta Orchestrator"]:::orch
        O3["Group Chat & Logging"]:::orch
    end

    %% Database Services and Dashboard
    DS["Database Services"]:::db
    DS1["Dashboard"]:::db

    %% Other Major Components
    MM["Memory Management"]:::memory
    PI["Primary Inference Services"]:::inference
    LI["Lightweight Inference (Minference)"]:::inference
    ES["Economic Simulation"]:::env
    EM["Economic Models"]:::econ
    VR["Verbal RL"]:::rl

    %% Connections

    %% Configurations drive Orchestrators
    CFG -->|"init_config"| O1

    %% Orchestrators coordinate Agents and Simulation
    O1 -->|"orchestrates"| A1
    O2 -->|"supports"| A1
    O3 -->|"logs_comm"| A1
    O1 -->|"triggers_sim"| ES

    %% Agents interactions
    A1 -->|"uses_memory"| MM
    A2 -->|"LLM_request"| PI
    PI -->|"LLM_response"| A2
    A3 -->|"uses_parallelInference"| PI
    A4 -->|"defines_behavior"| A1
    A5 -->|"influences_personas"| A4

    %% Database links
    DS -->|"stores_data"| A1
    DS -->|"persists_memory"| MM
    DS -->|"holds_simulation"| ES
    DS1 --> DS

    %% Simulation and Economic Models
    ES -->|"market_events"| A1
    EM -->|"econ_logic"| A1

    %% Alternate Inference Path
    LI -->|"alternative_inference"| A1

    %% Verbal RL influence
    VR -->|"modifies_rewards"| A1

    %% Additional interactions
    A2 -->|"economic_decision"| EM
    A3 -->|"rl_influence"| VR

    %% Class Definitions for Colors
    classDef agent fill:#FFF8DC,stroke:#FF8C00,stroke-width:2px;
    classDef orch fill:#E6E6FA,stroke:#800080,stroke-width:2px;
    classDef db fill:#DDFFDD,stroke:#228B22,stroke-width:2px;
    classDef memory fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
    classDef inference fill:#F0FFF0,stroke:#32CD32,stroke-width:2px;
    classDef env fill:#F5F5DC,stroke:#8B4513,stroke-width:2px;
    classDef econ fill:#FFE4E1,stroke:#FF69B4,stroke-width:2px;
    classDef rl fill:#E0FFFF,stroke:#20B2AA,stroke-width:2px;
    classDef config fill:#F0F8FF,stroke:#4682B4,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/agents/base_agent"
    click A2 "https://github.com/marketagents-ai/marketagents/blob/main/market_agents/agents/market_agent.py"
    click A3 "https://github.com/marketagents-ai/marketagents/blob/main/market_agents/agents/market_agent_prompter.py"
    click A4 "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/agents/personas"
    click A5 "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/agents/personas/weighted_personas"
    click DS "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/agents/db"
    click DS1 "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/agents/db/dashboard"
    click O1 "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/orchestrators"
    click MM "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/memory"
    click PI "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/inference"
    click LI "https://github.com/marketagents-ai/marketagents/tree/main/minference"
    click ES "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/environments"
    click EM "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/economics"
    click VR "https://github.com/marketagents-ai/marketagents/tree/main/market_agents/verbal_rl"
```
