# divishjindal19/finance_ai_agent architecture

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

- Interactive diagram: https://gitdiagram.com/divishjindal19/finance_ai_agent
- Repository: https://github.com/divishjindal19/finance_ai_agent

## Overview

##### Project Type and Purpose
- This is a Python-based, single-page financial analysis application built with Streamlit (front-end), a CrewAI multi-agent orchestration layer (back-end), and external services for data & inference. Its purpose is to fetch real-time financial data, run multiple specialized AI agents (via CrewAI) against that data using an LLM (Llama 4 on SambaNova hardware), and present consolidated insights in a web UI.

##### File-Structure Analysis
- Top-level files:
- .devcontainer/devcontainer.json – dev environment config
- .env – environment variables for API keys
- README.md – high-level overview & usage
- Core module: `multi_agent_financial_analyst/`
- `financial_analyst.py` – Streamlit entrypoint, orchestrates UI ↔ agents
- `requirements.txt` – Python dependencies (CrewAI, yfinance, llama4, etc.)
- `tools/financial_tools.py` – utility functions for data fetching & preprocessing

##### Key Architecture Insights from README
- Multi-agent design using CrewAI
- Real-time data ingestion via YFinance
- LLM inference (Llama 4) accelerated on SambaNova platform
- Modular design: new agents / tools can be plugged in

##### Main Components & Their Roles
A. Streamlit UI Layer (financial_analyst.py)
- Renders input forms (tickers, date ranges, analysis options)
- Displays charts and textual insights returned by agents
B. CrewAI Orchestrator
- Manages a set of agents (e.g., Market-Trend Agent, Risk-Analysis Agent, Valuation Agent)
- Dispatches tasks in parallel, aggregates results
C. Agent Modules (inside CrewAI framework)
- Each agent encapsulates a role: fetch data, run analysis via LLM, post-process
- They import shared utilities from `tools/financial_tools.py`
D. Financial Tools Library
- Data fetchers (YFinance API wrappers)
- Data normalization, feature extraction functions
E. External Services
1. YFinance REST API – real-time & historical financial data
2. SambaNova LLM Inference Endpoint – hosts Llama 4 model

##### Interactions & Data Flow
1. End-user interacts with Streamlit UI → selects tickers & options.
2. UI invokes CrewAI orchestrator API → spawns multiple agents.
3. Agents call Financial Tools → fetch raw data from YFinance.
4. Agents send prompts & data to Llama 4 inference endpoint on SambaNova.
5. LLM returns analysis snippets → agents post-process & return.
6. Orchestrator aggregates agent outputs → returns final result to UI.
7. UI renders charts & narrative summaries.

##### Architectural Patterns & Principles
- Multi-agent (concurrent workers with distinct roles)
- Modular separation: UI, orchestration, utilities, external services
- Dependency inversion: business logic (agents) depends on abstracted tool interfaces
- Extensibility: new agent modules or tool functions can be dropped into `tools/`

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        ENV[".env"]:::config
        REQ["requirements.txt"]:::config
        DEV[".devcontainer/devcontainer.json"]:::config
        DOC["README.md"]:::config
    end

    subgraph "Frontend Layer"
        UI["Streamlit UI\n(financial_analyst.py)"]:::frontend
    end

    subgraph "Backend Layer"
        ORCH(["CrewAI Orchestrator"]):::backend
        subgraph "Agent Pool"
            MTA["Market-Trend Agent"]:::agent
            RAA["Risk-Analysis Agent"]:::agent
            VA["Valuation Agent"]:::agent
        end
        TOOLS[/Financial Tools Library/]:::tools
    end

    subgraph "External Services"
        YF["YFinance API"]:::external
        SN["SambaNova LLM Service"]:::external
    end

    %% Data Flows
    UI -->|HTTP/JSON| ORCH
    ORCH -->|spawn tasks| MTA
    ORCH -->|spawn tasks| RAA
    ORCH -->|spawn tasks| VA
    MTA -->|uses| TOOLS
    RAA -->|uses| TOOLS
    VA -->|uses| TOOLS
    TOOLS -->|REST/JSON| YF
    MTA -->|HTTP/JSON prompts| SN
    RAA -->|HTTP/JSON prompts| SN
    VA -->|HTTP/JSON prompts| SN
    MTA -->|returns result| ORCH
    RAA -->|returns result| ORCH
    VA -->|returns result| ORCH
    ORCH -->|aggregated result| UI

    %% Configuration Dependencies
    ENV -.-> UI
    ENV -.-> ORCH
    REQ -.-> UI
    REQ -.-> ORCH
    DEV -.-> ORCH
    DOC -.-> UI

    %% Click Events
    click UI "https://github.com/divishjindal19/finance_ai_agent/blob/main/multi_agent_financial_analyst/financial_analyst.py"
    click TOOLS "https://github.com/divishjindal19/finance_ai_agent/blob/main/multi_agent_financial_analyst/tools/financial_tools.py"
    click REQ "https://github.com/divishjindal19/finance_ai_agent/blob/main/multi_agent_financial_analyst/requirements.txt"
    click ENV "https://github.com/divishjindal19/finance_ai_agent/blob/main/.env"
    click DEV "https://github.com/divishjindal19/finance_ai_agent/blob/main/.devcontainer/devcontainer.json"
    click DOC "https://github.com/divishjindal19/finance_ai_agent/blob/main/README.md"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef agent fill:#98FB98,stroke:#333,stroke-width:1px
    classDef tools fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#F0E68C,stroke:#333,stroke-width:1px,stroke-dasharray:2 2
```
