# dvampire/finagent architecture

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

- Interactive diagram: https://gitdiagram.com/dvampire/finagent
- Repository: https://github.com/dvampire/finagent

## Overview

- Data Downloaders – From both the “configs/downloader” and “finagent/downloader” directories, these modules handle fetching news, day prices, and economic data. Indicate that these modules retrieve and store raw data.
- Data Processing Layer – Components like “finagent/processor” and tools in the “tools” directory are responsible for cleaning and converting the raw data into structured formats. Also include “tools/data_process.py” as the entry point.
- Data and Asset Management – The “finagent/asset” and “finagent/data” modules manage asset lists and dataset definitions.
- Memory & Storage – The “finagent/memory” module (including FAISS) is used for retaining historical data and context – crucial for machine learning models and decision making.
- Decision & Strategy Modules – The “finagent/prompt” (with its trading submodules), “finagent/provider” and “finagent/tools/strategy_agents” encapsulate logic for generating trading decisions. Also include “finagent/trajectory” which implements dynamic programming – part of strategy optimization.
- Visualization & Metrics – “finagent/plots” and “finagent/metrics” cater to result visualizations (like Kline charts) and tracking performance metrics.
- Configuration and Experimentation – The “configs” folder (with its asset lists, trading strategies experiments in “configs/exp”, and processor configs) and “res/strategy_record” illustrate the experimental record and customized configuration aspects.

##### Interactions and Data Flow
- That once data is fetched, it is passed to the Data Processing layer, which cleans and structures the data.
- Visualization side: once decisions are made, performance metrics (via “finagent/metrics” and “finagent/plots”) are generated and optionally stored or displayed.
- Experimental branch where configurations (from “configs/exp”) and recorded strategy results (in “res/strategy_record”) are used for training and refining strategies.

##### Architectural Patterns and Technologies
- The system uses a modular, layered architecture. Each component (Downloader, Processor, Memory, Decision-making) is roughly isolated, communicating via well-defined interfaces.
- The separation of concerns is evident – configurations, data acquisition, processing, memory management, decision prompting, and visualization are split into distinct modules.
- Technologies include Python 3.10, FAISS (for memory), Playwright (for web automation), and various API clients for data retrieval.
- The extensive use of prompts and template files (in “res/prompts”) suggests that the system leverages language model interactions and dynamic decision frameworks.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Data Sources
    subgraph "External Data Sources"
        FAP["FMP API"]:::external
        POL["Polygon API"]:::external
        YF["Yahoo Finance API"]:::external
        RAP["RapidAPI"]:::external
        OAHF["OpenAI/HuggingFace API"]:::external
    end

    %% Data Downloaders
    subgraph "Data Downloaders"
        CD["Configs Downloader"]:::downloader
        ID["Internal Downloader"]:::downloader
        DN["Download News"]:::downloader
        DP["Download Prices"]:::downloader
        DE["Download Economic"]:::downloader
        DS["Download Sentiment"]:::downloader
    end

    %% Data Processing Layer
    subgraph "Data Processing Layer"
        CP["Configs Processor"]:::processing
        IP["Internal Processor"]:::processing
        DPS["Data Process Script"]:::processing
    end

    %% Core FinAgent Modules
    subgraph "Core FinAgent Modules"
        subgraph "Data & Asset Management"
            AM["Asset Management"]:::asset
            DM["Data Management"]:::asset
        end
        subgraph "Memory & Storage"
            MM["Memory Module"]:::memory
        end
        subgraph "Decision & Strategy"
            DPm["Decision Prompt"]:::decision
            PM["Provider Module"]:::decision
            TM["Trajectory Module"]:::decision
            SA["Strategy Agents"]:::decision
            MS["Main Strategy"]:::decision
            MI["Main MI Decision"]:::decision
            MIL["Main MI Low Decision"]:::decision
        end
    end

    %% Visualization & Metrics
    subgraph "Visualization & Metrics"
        V["Visualization"]:::visualize
        M["Metrics"]:::visualize
    end

    %% Configuration & Experimentation
    subgraph "Configuration & Experimentation"
        C["Configurations"]:::config
        SR["Strategy Records"]:::config
        OC["OpenAI Config"]:::config
    end

    %% Connections from External Data Sources to Data Downloaders
    FAP -->|"fetch"| CD
    POL -->|"fetch"| ID
    YF -->|"fetch"| CD
    RAP -->|"fetch"| ID
    OAHF -->|"fetch"| ID

    %% Connections from Data Downloaders to Data Processing Layer
    CD -->|"raw_data"| CP
    ID -->|"raw_data"| IP
    DN -->|"news_data"| DPS
    DP -->|"prices_data"| DPS
    DE -->|"economic_data"| DPS
    DS -->|"sentiment_data"| DPS

    %% Connections from Data Processing Layer to Core FinAgent Modules
    CP -->|"processed"| AM
    IP -->|"processed"| DM
    DPS -->|"processed"| MM
    DPS -->|"processed"| DPm
    MM -->|"context"| DPm

    %% Internal Decision Flow within Decision & Strategy Modules
    DPm -->|"flow"| PM
    PM -->|"flow"| TM
    TM -->|"flow"| SA
    SA -->|"flow"| MS
    MS -->|"detail"| MI
    MI -->|"detail"| MIL

    %% Decision to Visualization
    MS -->|"trading_decisions"| V

    %% Visualization & Metrics connections
    V -->|"performance"| C
    M -->|"record_storage"| SR

    %% Feedback loop from Configuration back to Processing and Downloaders
    C -->|"config_update"| CP
    C -->|"config_update"| CD
    C -->|"includes"| OC

    %% Styles
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef downloader fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef processing fill:#ccccff,stroke:#000066,stroke-width:2px;
    classDef asset fill:#e6ccff,stroke:#800080,stroke-width:2px;
    classDef memory fill:#ffe6cc,stroke:#ff9900,stroke-width:2px;
    classDef decision fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef visualize fill:#ccffff,stroke:#009999,stroke-width:2px;
    classDef config fill:#f2e6d9,stroke:#b38b6d,stroke-width:2px;

    %% Click Events for Data Downloaders
    click CD "https://github.com/dvampire/finagent/tree/main/configs/downloader"
    click ID "https://github.com/dvampire/finagent/tree/main/finagent/downloader"
    click DN "https://github.com/dvampire/finagent/blob/main/tools/download_news.py"
    click DP "https://github.com/dvampire/finagent/blob/main/tools/download_prices.py"
    click DE "https://github.com/dvampire/finagent/blob/main/tools/download_economic.py"
    click DS "https://github.com/dvampire/finagent/blob/main/tools/download_sentiment.py"

    %% Click Events for Data Processing Layer
    click CP "https://github.com/dvampire/finagent/tree/main/configs/processor"
    click IP "https://github.com/dvampire/finagent/tree/main/finagent/processor"
    click DPS "https://github.com/dvampire/finagent/blob/main/tools/data_process.py"

    %% Click Events for Data and Asset Management
    click AM "https://github.com/dvampire/finagent/tree/main/finagent/asset"
    click DM "https://github.com/dvampire/finagent/tree/main/finagent/data"

    %% Click Event for Memory & Storage
    click MM "https://github.com/dvampire/finagent/tree/main/finagent/memory"

    %% Click Events for Decision & Strategy Modules
    click DPm "https://github.com/dvampire/finagent/tree/main/finagent/prompt"
    click PM "https://github.com/dvampire/finagent/tree/main/finagent/provider"
    click TM "https://github.com/dvampire/finagent/tree/main/finagent/trajectory"
    click SA "https://github.com/dvampire/finagent/blob/main/finagent/tools/strategy_agents.py"
    click MS "https://github.com/dvampire/finagent/blob/main/tools/main_strategy.py"
    click MI "https://github.com/dvampire/finagent/blob/main/tools/main_mi_w_decision.py"
    click MIL "https://github.com/dvampire/finagent/blob/main/tools/main_mi_w_low_w_decision.py"

    %% Click Events for Visualization & Metrics
    click V "https://github.com/dvampire/finagent/tree/main/finagent/plots"
    click M "https://github.com/dvampire/finagent/tree/main/finagent/metrics"

    %% Click Events for Configuration & Experimentation
    click C "https://github.com/dvampire/finagent/tree/main/configs"
    click SR "https://github.com/dvampire/finagent/tree/main/res/strategy_record"
    click OC "https://github.com/dvampire/finagent/blob/main/configs/openai_config.json"
```
