# heurist-network/heurist-agent-framework architecture

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

- Interactive diagram: https://gitdiagram.com/heurist-network/heurist-agent-framework
- Repository: https://github.com/heurist-network/heurist-agent-framework

## Overview

##### Project Type and Purpose
- The Heurist Agent Framework is a modular, multi-interface AI agent platform. Its purpose is to process text/voice, generate images and videos, and interact on various platforms (Telegram, Discord, Twitter, Farcaster, REST API, and more).
- It is built to leverage a “mesh” of specialized agents (the Mesh section) that can interact and compose workflows (similar to modular smart contracts in DeFi) and easily integrate with external systems via MCP and other clients.

##### File Structure
- Key directories include:
- core: Contains the core logic, configuration, LLM integration, utilities (like image and video generation).
- agents: Implements base functionalities for core agents, research agents, and tool-decorators.
- interfaces & platforms: Provide platform-specific implementations (Discord, Telegram, Twitter, Farcaster, REST API) that interact with the core agent.
- mesh: Houses a collection of specialized agent scripts. These “Mesh Agents” extend functionality by offering specific processing (e.g., token info, search agents, analytics).
- clients: Contains API client implementations for external services (e.g., Defillama, MCP client, Merkl, etc.).
- config: Manages configuration files (e.g., YAML prompts) to drive agent behavior.
- examples & docs: Offer usage examples and documentation.
- There are multiple main entry point scripts (e.g., main_api.py, main_discord.py, etc.) that launch agents on different interfaces, indicating separate runtime components communicating with the same core.

##### Essential Elements
- From external platforms to the Core Agent.
- From the Core Agent to Mesh Agents.
- Between the Core Agent and external API clients.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Top Layer: External Interfaces
    subgraph "External Interfaces"
        Telegram["Telegram Bot"]:::interfaces
        Discord["Discord Bot"]:::interfaces
        Twitter["Twitter Bot"]:::interfaces
        RESTAPI["REST API"]:::interfaces
        Farcaster["Farcaster Integration"]:::interfaces
    end

    %% Middle Layer: Core Agent Module
    subgraph "Core Agent Module"
        AgentController["Agent Controller"]:::core
        LLMConfig["LLM & Config"]:::core
        AgentController ---|"internal"| LLMConfig
    end

    %% Bottom Layer: Supporting Services
    subgraph "Supporting Services"
        MeshAgents["Mesh Agents"]:::mesh
        APIClients["API Clients"]:::clients
        Utilities["Utilities"]:::clients
        ConfigNode["Configuration"]:::config
        EnvNode["Environment"]:::config
    end

    %% Connections from Interfaces to Core
    Telegram -->|"user_input"| AgentController
    Discord -->|"user_input"| AgentController
    Twitter -->|"user_input"| AgentController
    RESTAPI -->|"API_call"| AgentController
    Farcaster -->|"user_input"| AgentController

    %% Connections from Core to Supporting Services
    AgentController -->|"orchestrates"| MeshAgents
    MeshAgents ---|"data_exchange"| AgentController

    AgentController -->|"external_call"| APIClients
    AgentController -->|"utilizes"| Utilities
    AgentController -->|"loads"| ConfigNode
    AgentController -->|"loads"| EnvNode

    %% Additional inter-service communication
    MeshAgents -->|"fetch_data"| APIClients
    APIClients -->|"support"| Utilities

    %% Click Events for External Interfaces
    click Telegram "https://github.com/heurist-network/heurist-agent-framework/blob/main/interfaces/telegram.py"
    click Discord "https://github.com/heurist-network/heurist-agent-framework/blob/main/interfaces/discord.py"
    click Twitter "https://github.com/heurist-network/heurist-agent-framework/blob/main/interfaces/twitter_post.py"
    click RESTAPI "https://github.com/heurist-network/heurist-agent-framework/blob/main/interfaces/api.py"
    click Farcaster "https://github.com/heurist-network/heurist-agent-framework/tree/main/interfaces/"

    %% Click Events for Core Agent Module
    click AgentController "https://github.com/heurist-network/heurist-agent-framework/blob/main/agents/core_agent.py"
    click LLMConfig "https://github.com/heurist-network/heurist-agent-framework/blob/main/core/llm.py"
    click LLMConfig "https://github.com/heurist-network/heurist-agent-framework/blob/main/core/config.py"

    %% Click Event for Mesh Agents
    click MeshAgents "https://github.com/heurist-network/heurist-agent-framework/tree/main/mesh/"

    %% Click Events for External Clients & Tools
    click APIClients "https://github.com/heurist-network/heurist-agent-framework/tree/main/clients/"
    click Utilities "https://github.com/heurist-network/heurist-agent-framework/blob/main/utils/llm_utils.py"

    %% Click Events for Configuration and Environment
    click ConfigNode "https://github.com/heurist-network/heurist-agent-framework/tree/main/config/"
    click EnvNode "https://github.com/heurist-network/heurist-agent-framework/blob/main/.env.example"

    %% Styles
    classDef interfaces fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef core fill:#C2FABA,stroke:#333,stroke-width:2px;
    classDef mesh fill:#FFF5BA,stroke:#333,stroke-width:2px;
    classDef clients fill:#F7C8BA,stroke:#333,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
