# dataguru9/akasei-hedgefund-agent architecture

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

- Interactive diagram: https://gitdiagram.com/dataguru9/akasei-hedgefund-agent
- Repository: https://github.com/dataguru9/akasei-hedgefund-agent

## Overview

##### Project Type and Purpose
- This is a Python-based, modular, command-line “backend” application (no GUI/front-end) that simulates an AI-driven hedge fund.
- It fetches market data, runs multiple AI agents (via LLMs and traditional analytics), manages risk, constructs portfolios, and optionally backtests strategies.

##### Major Components
A. External Services
- Financial Data API (financialdatasets.ai)
- LLM Providers (OpenAI, Groq, Anthropic, plus local Ollama)
B. Data Layer (src/data)
- Cache manager (cache.py)
- Domain models (models.py)
C. LLM Abstraction Layer
- OpenAI/Groq API wrappers (src/utils/ollama.py, src/ollama_utils.py)
- llm models definitions (src/llm/models.py)
D. Agent Modules (src/agents)
1. Named Strategist Agents (ben_graham.py, bill_ackman.py, … warren_buffett.py)
2. Specialized Analysis Agents (valuation.py, fundamentals.py, sentiment.py, technicals.py)
3. Risk Manager (risk_manager.py)
4. Portfolio Manager (portfolio_manager.py)
E. Orchestration & Core Logic
- Main entry point (src/main.py) – live mode
- Backtester (src/backtester.py) – historical simulation
- State machine / workflow graph (src/graph/state.py)
F. Utility Modules (src/utils)
- Data fetching and API tools (src/tools/api.py)
G. Output/Visualization
- Console logs (–show-reasoning)

##### Relationships and Data Flows
1. Orchestrator (main.py/backtester.py) invokes Data Layer → fetches raw market data via API tools → caching
2. Preprocessed data objects flow into the Graph/State manager → dispatches to each analysis agent
3. Each Agent requests LLMs (via LLM Abstraction) and/or applies rule-based logic → produces signals
4. Signals feed into Risk Manager → position sizing
5. Risk-adjusted signals feed into Portfolio Manager → final orders
6. Orders → trade simulation / backtester → performance results
7. Utility modules handle logging, progress bars, and chart generation

##### Architectural Patterns and Principles
- Modular pipeline: clearly separated layers for data, analysis, orchestration, and output
- Dependency inversion: agents depend on LLM abstraction rather than raw API calls
- Single responsibility: each agent module implements one style of analysis
- Extensibility: new agents can be dropped into src/agents and wired via the state graph

## Diagram (Mermaid)

```mermaid
flowchart TB
    title["AI Hedge Fund System Architecture"]

    %% External Services
    subgraph "External Services"
        API["Financial Data API"]:::external
        LLMProviders["LLM Providers\n(OpenAI, Groq, Anthropic, Ollama)"]:::external
    end

    %% Data Layer
    subgraph "Data Layer"
        Cache["Cache Manager\n(src/data/cache.py)"]:::core
        Models["Domain Models\n(src/data/models.py)"]:::core
    end

    %% LLM Abstraction Layer
    subgraph "LLM Abstraction Layer"
        OllamaLocal["Ollama Local Wrapper\n(src/ollama_utils.py)"]:::core
        LLMUtils["General LLM Utils\n(src/utils/llm.py)"]:::core
        OllamaUtils["Ollama Utils\n(src/utils/ollama.py)"]:::core
        LLMModels["LLM Model Definitions\n(src/llm/models.py)"]:::core
    end

    %% Agents
    subgraph "Agent Modules"
        subgraph "Strategy Agents"
            BG["Benjamin Graham"]:::agent
            BA["Bill Ackman"]:::agent
            CW["Cathie Wood"]:::agent
            CM["Charlie Munger"]:::agent
            MB["Michael Burry"]:::agent
            PL["Peter Lynch"]:::agent
            PF["Phil Fisher"]:::agent
            SD["Stanley Druckenmiller"]:::agent
            WB["Warren Buffett"]:::agent
        end
        subgraph "Analysis Agents"
            VAL["Valuation"]:::agent
            FUND["Fundamentals"]:::agent
            SENT["Sentiment"]:::agent
            TECH["Technicals"]:::agent
        end
        RM["Risk Manager\n(src/agents/risk_manager.py)"]:::agent
        PM["Portfolio Manager\n(src/agents/portfolio_manager.py)"]:::agent
    end

    %% Orchestration & Core Logic
    subgraph "Orchestration & Core Logic"
        Main["Live Mode Entry (src/main.py)"]:::orchestrator
        Back["Backtester (src/backtester.py)"]:::orchestrator
        State["State Machine\n(src/graph/state.py)"]:::orchestrator
    end

    %% Utilities & Output
    subgraph "Utilities & Output"
        APItools["API Tools\n(src/tools/api.py)"]:::util
        Display["Display & Logging\n(src/utils/display.py)"]:::util
        Progress["Progress Tracking\n(src/utils/progress.py)"]:::util
        Viz["Visualization (Charts)\n(src/utils/visualize.py)"]:::util
    end

    %% Data Flow
    API -->|"fetch MarketData"| APItools --> Cache --> Models
    Models -->|"preprocessed data"| State
    State -->|"dispatch MarketData"| BG & BA & CW & CM & MB & PL & PF & SD & WB & VAL & FUND & SENT & TECH
    BG & BA & CW & CM & MB & PL & PF & SD & WB & VAL & FUND & SENT & TECH -->|"Signal"| RM
    RM -->|"Risk-adjusted Signal"| PM
    PM -->|"Order"| Main
    PM -->|"Order"| Back
    Main -->|"Results"| Viz
    Back -->|"Simulation Results"| Viz

    %% LLM Integration
    BG & BA & CW & CM & MB & PL & PF & SD & WB & VAL & FUND & SENT & TECH -->|"LLM Request"| OllamaLocal & LLMUtils & OllamaUtils & LLMModels
    LLMProviders -->|"LLM Endpoint"| OllamaLocal & LLMUtils & OllamaUtils

    %% Utilities hooks
    APItools --> Display
    State --> Progress
    Main --> Display
    Back --> Display
    Viz --> Display

    %% Click Events
    click Cache "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/data/cache.py"
    click Models "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/data/models.py"
    click OllamaLocal "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/ollama_utils.py"
    click LLMUtils "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/utils/llm.py"
    click OllamaUtils "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/utils/ollama.py"
    click LLMModels "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/llm/models.py"
    click BG "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/ben_graham.py"
    click BA "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/bill_ackman.py"
    click CW "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/cathie_wood.py"
    click CM "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/charlie_munger.py"
    click MB "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/michael_burry.py"
    click PL "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/peter_lynch.py"
    click PF "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/phil_fisher.py"
    click SD "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/stanley_druckenmiller.py"
    click WB "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/warren_buffett.py"
    click VAL "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/valuation.py"
    click FUND "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/fundamentals.py"
    click SENT "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/sentiment.py"
    click TECH "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/technicals.py"
    click RM "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/risk_manager.py"
    click PM "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/agents/portfolio_manager.py"
    click Main "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/main.py"
    click Back "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/backtester.py"
    click State "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/graph/state.py"
    click APItools "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/tools/api.py"
    click Display "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/utils/display.py"
    click Progress "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/utils/progress.py"
    click Viz "https://github.com/dataguru9/akasei-hedgefund-agent/blob/main/src/utils/visualize.py"

    %% Styles
    classDef external fill:#e0ffe0,stroke:#009900;
    classDef core fill:#e0f0ff,stroke:#0066cc;
    classDef agent fill:#cce5ff,stroke:#0059b3;
    classDef orchestrator fill:#ffe6cc,stroke:#ff8000;
    classDef util fill:#f0e0ff,stroke:#8000b3;
    class title fill:#ffffff,stroke:none,font-weight:bold;
```
