# ai4finance-foundation/fingpt architecture

> Architecture diagram of the GitHub repository ai4finance-foundation/fingpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai4finance-foundation/fingpt
- Repository: https://github.com/ai4finance-foundation/fingpt

## Overview

1. Repository shape
This is a monorepo split into two major worlds: FinGPT, which is a research/training/inference stack for finance-oriented LLMs, and Finogrid, which is a service platform that operationalizes LLM-driven financial workflows. Most of the “apps” are notebook- and script-driven rather than packaged web apps.

2. FinGPT core: model lifecycle
The FinGPT side is organized around the full LLM lifecycle: data preparation, instruction tuning, evaluation/benchmarking, and demo inference. The code is mostly Python, with shell scripts for reproducible runs and notebooks for experimentation. It is centered on lightweight adaptation methods such as LoRA / QLoRA on top of base models like Llama, ChatGLM2, Falcon, MPT, Bloom, and Qwen.

3. Benchmarking subsystem
`fingpt/FinGPT_Benchmark` is the main task-evaluation layer. It contains dataset download/prepare utilities, task-specific benchmark definitions, and LoRA training entrypoints. The benchmark tasks are financial sentiment, relation extraction, headline classification, NER, QA, and Chinese multiple-choice evaluation. Data flows from benchmark datasets → preprocessing/download scripts → train/eval scripts → task metrics and model comparison.

4. Financial sentiment analysis lineage
`fingpt/FinGPT_Sentiment_Analysis_v1` and `v3` are earlier/end-to-end sentiment pipelines. They include data preparation, dataset conversion, tokenization, and fine-tuning paths for Chinese and English financial sentiment. These directories show the repository’s progression from dataset construction to model training to benchmark reporting.

5. Forecasting subsystem
`fingpt/FinGPT_Forecaster` is a separate application track focused on stock movement prediction and robo-advice. Its pipeline combines market data, news, indices, sentiment, and prompts; the main Python modules (`data_pipeline.py`, `market_sentiment.py`, `indices.py`, `prompt.py`, `app.py`) indicate a preprocessing-to-prediction flow. This area also has a Chinese variant and notebook-based training/inference artifacts. The README makes clear this subsystem can run with local FinGPT models or external cloud LLMs.

6. RAG and retrieval-based sentiment
`fingpt/FinGPT_RAG` contains two distinct parts: `instruct-FinGPT` for supervised fine-tuning/inference, and `multisource_retrieval` for retrieval-augmented sentiment analysis. The retrieval pipeline scrapes multiple news sources, normalizes and splits text, classifies sources, and optionally uses external LLM providers. This is the main boundary where data collection, retrieval, and LLM inference are combined into a context-enriched sentiment system.

7. Financial report analysis
`fingpt/FinGPT_FinancialReportAnalysis` is a smaller but separate RAG-style workflow for earnings calls and PDF/report processing. Utilities for PDF formatting, earnings-call handling, and retrieval indicate a pipeline from unstructured financial documents to summarized or question-answering outputs.

8. Multi-agent and evaluation experiments
`fingpt/FinGPT_MultiAgentsRAG` groups multi-agent retrieval experiments, fine-tuning notebooks, and evaluation suites such as MMLU, TruthfulQA, and HaluEval. Architecturally, this is an experimentation layer that compares multi-agent reasoning against RAG and tuned models, rather than a production service.

9. “Other” application demos
`fingpt/FinGPT_Others` holds application prototypes such as robo-advisors, trading assistants, and low-code development examples. These are downstream consumers of the same LLM/data primitives used elsewhere in the repo, but they are not a single shared runtime; they are mostly notebook-driven demos with their own datasets and helper scripts.

10. Finogrid platform: operational layer
`finogrid/` is the production-oriented platform. It is split into service APIs, domain logic, database schema/models, corridor adapters, MCP integrations, and a TypeScript SDK. This part is more explicitly service-oriented and is where FinGPT capabilities are embedded into a larger orchestration system.

11. Finogrid request/data flow
The Finogrid service layer suggests a pipeline like: ingress API receives requests, routing engine selects execution paths, partner execution sends work outward, reconciliation closes the loop, and agent-ledger services record accounting/payment state. `ops_console` provides operator-facing views over approvals, corridors, exceptions, mandates, and ledger data. `agent_ledger_api` handles wallet/payment/top-up/KYA/micropay concerns, while middleware such as payment gating sits in front of protected operations.

12. Corridors and external integrations
`finogrid/corridors` contains country-specific adapters (Argentina, Brazil, India, Indonesia, Nigeria, Philippines, UAE, Vietnam) built on a shared base interface. `finogrid/mcp` contains connector-style servers for bridge, identity, KYA/KYT, Plaid, and wallet factory, which are the platform’s external-service boundaries. This is the integration layer for banking/compliance/identity and other regulated financial infrastructure.

13. FinGPT integration inside Finogrid
`finogrid/fingpt_integration` is the bridge from platform services to LLM capabilities: sentiment, forecaster, and RAG modules. It also includes provider selection and fallback logic for cloud LLMs such as MiniMax or OpenAI versus local FinGPT models. This boundary is important architecturally: platform services depend on a pluggable LLM provider interface rather than a single model backend.

14. Persistence, SDK, and tooling
Finogrid persists operational state through SQL migrations and Python ORM-style models under `database/`. The TypeScript SDK under `sdk/typescript` exposes the platform to external clients. Across the repo, notebooks, shell scripts, config JSON, and requirements files are the main orchestration/tooling mechanism, showing that reproducibility and experimentation are first-class concerns alongside service deployment.

Main entry points: [`fingpt`](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt) (FinGPT), [`finogrid/fingpt_integration`](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/fingpt_integration) (FinGPT Bridge), [`finogrid/database`](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/database) (Database), [`fingpt/FinGPT_Benchmark`](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Benchmark) (Benchmarking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_fingpt["FinGPT"]
  node_fingpt_root["FinGPT<br/>monorepo research stack"]
  node_benchmark["Benchmarking<br/>task eval suite"]
  node_sent_v1["Sentiment v1<br/>sentiment pipeline"]
  node_sent_v3["Sentiment v3<br/>sentiment pipeline"]
  node_forecaster["Forecaster<br/>prediction app"]
  node_rag["RAG Sentiment<br/>retrieval workflow"]
  node_report_rag["Report Analysis<br/>document RAG"]
  node_multiagents["Multi-Agents<br/>experiments"]
  node_others["Other Demos<br/>application demos"]
end

subgraph group_finogrid["Finogrid"]
  node_finogrid_root["Finogrid<br/>operational platform"]
  node_ingress_api["Ingress API<br/>request gateway"]
  node_routing_engine["Routing Engine<br/>workflow router"]
  node_partner_exec["Partner Exec<br/>execution adapter"]
  node_reconciliation["Reconciliation<br/>state closure"]
  node_ledger_api["Agent Ledger<br/>wallet/ledger api"]
  node_ops_console["Ops Console<br/>operator ui"]
  node_corridors["Corridors<br/>country adapters"]
  node_mcp["MCP Integrations<br/>external connectors"]
  node_fingpt_integration["FinGPT Bridge<br/>llm integration layer"]
  node_database[("Database<br/>schema/models")]
  node_sdk_ts["TypeScript SDK<br/>client sdk"]
end

node_fingpt_root -->|"organizes"| node_benchmark
node_fingpt_root -->|"contains"| node_sent_v1
node_fingpt_root -->|"contains"| node_sent_v3
node_fingpt_root -->|"contains"| node_forecaster
node_fingpt_root -->|"contains"| node_rag
node_fingpt_root -->|"contains"| node_report_rag
node_fingpt_root -->|"contains"| node_multiagents
node_fingpt_root -->|"contains"| node_others
node_benchmark -->|"evolves from"| node_sent_v1
node_sent_v1 -->|"iterates to"| node_sent_v3
node_benchmark -.->|"shares tasks"| node_rag
node_forecaster -->|"uses"| node_fingpt_integration
node_rag -->|"feeds"| node_fingpt_integration
node_report_rag -->|"feeds"| node_fingpt_integration
node_finogrid_root -->|"exposes"| node_ingress_api
node_ingress_api -->|"dispatches"| node_routing_engine
node_routing_engine -->|"routes"| node_partner_exec
node_partner_exec -->|"returns"| node_reconciliation
node_ingress_api -->|"authorizes"| node_ledger_api
node_ledger_api -->|"persists"| node_database
node_routing_engine -->|"reads/writes"| node_database
node_reconciliation -->|"updates"| node_database
node_ops_console -->|"observes"| node_database
node_corridors -->|"integrates"| node_mcp
node_fingpt_integration -->|"exposes"| node_sdk_ts
node_fingpt_integration -.->|"consumes state"| node_database
node_ops_console -->|"oversees"| node_ledger_api

click node_fingpt_root "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt"
click node_benchmark "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Benchmark"
click node_sent_v1 "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Sentiment_Analysis_v1"
click node_sent_v3 "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Sentiment_Analysis_v3"
click node_forecaster "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Forecaster"
click node_rag "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_RAG"
click node_report_rag "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_FinancialReportAnalysis"
click node_multiagents "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_MultiAgentsRAG"
click node_others "https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Others"
click node_finogrid_root "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid"
click node_ingress_api "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/ingress_api"
click node_routing_engine "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/routing_engine"
click node_partner_exec "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/partner_execution"
click node_reconciliation "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/reconciliation"
click node_ledger_api "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/agent_ledger_api"
click node_ops_console "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/ops_console"
click node_corridors "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/corridors"
click node_mcp "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/mcp"
click node_fingpt_integration "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/fingpt_integration"
click node_database "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/database"
click node_sdk_ts "https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/sdk/typescript"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fingpt_root,node_benchmark,node_sent_v1,node_sent_v3,node_forecaster,node_rag,node_report_rag,node_multiagents,node_others toneBlue
class node_finogrid_root,node_ingress_api,node_routing_engine,node_partner_exec,node_reconciliation,node_ledger_api,node_ops_console,node_corridors,node_mcp,node_fingpt_integration,node_database,node_sdk_ts toneAmber
```

## Components

### FinGPT

Research, training, evaluation, and demo workflows for finance-oriented LLMs.

- [FinGPT](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt): monorepo research stack · Top-level FinGPT workspace for model lifecycle experiments and finance applications. · `fingpt`
- [Benchmarking](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Benchmark): task eval suite · Dataset prep, benchmark definitions, LoRA training, and evaluation for finance tasks. · `fingpt/FinGPT_Benchmark`
- [Sentiment v1](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Sentiment_Analysis_v1): sentiment pipeline · Early end-to-end sentiment workflow with data preparation, dataset construction, and training. · `fingpt/FinGPT_Sentiment_Analysis_v1`
- [Sentiment v3](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Sentiment_Analysis_v3): sentiment pipeline · Later sentiment stack with benchmark notebooks and quantized training variants. · `fingpt/FinGPT_Sentiment_Analysis_v3`
- [Forecaster](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Forecaster): prediction app · Stock movement prediction and robo-advice pipeline from market/news inputs to prompts and inference. · `fingpt/FinGPT_Forecaster`
- [RAG Sentiment](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_RAG): retrieval workflow · Instruction tuning plus multi-source retrieval-augmented sentiment analysis. · `fingpt/FinGPT_RAG`
- [Report Analysis](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_FinancialReportAnalysis): document RAG · Earnings-call and PDF/report processing for summarization and Q&A. · `fingpt/FinGPT_FinancialReportAnalysis`
- [Multi-Agents](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_MultiAgentsRAG): experiments · Multi-agent retrieval experiments and evaluation against benchmark suites. · `fingpt/FinGPT_MultiAgentsRAG`
- [Other Demos](https://github.com/ai4finance-foundation/fingpt/tree/master/fingpt/FinGPT_Others): application demos · Notebook-driven robo-advisor, trading, and low-code prototypes built on shared LLM primitives. · `fingpt/FinGPT_Others`

### Finogrid

Operational platform for LLM-driven financial workflows, integrations, and ledgers.

- [Finogrid](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid): operational platform · Production-oriented service platform for routing, execution, compliance, and ledger state. · `finogrid`
- [Ingress API](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/ingress_api): request gateway · Public entrypoint for onboarding, batch submission, and webhook traffic. · `finogrid/services/ingress_api`
- [Routing Engine](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/routing_engine): workflow router · Selects execution paths and coordinates routing workers. · `finogrid/services/routing_engine`
- [Partner Exec](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/partner_execution): execution adapter · Dispatches work to external partners and bridge clients. · `finogrid/services/partner_execution`
- [Reconciliation](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/reconciliation): state closure · Closes the loop by reconciling execution results and operational state. · `finogrid/services/reconciliation`
- [Agent Ledger](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/agent_ledger_api): wallet/ledger api · Wallet, micropay, top-up, and KYA/KYT services with payment gating. · `finogrid/services/agent_ledger_api`
- [Ops Console](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/services/ops_console): operator ui · Operator-facing views for approvals, corridors, exceptions, mandates, and ledger exploration. · `finogrid/services/ops_console`
- [Corridors](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/corridors): country adapters · Country-specific corridor adapters over a shared base interface. · `finogrid/corridors`
- [MCP Integrations](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/mcp): external connectors · Connector-style servers for identity, KYA/KYT, plaid, bridge, and wallet factory. · `finogrid/mcp`
- [FinGPT Bridge](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/fingpt_integration): llm integration layer · Pluggable FinGPT/cloud LLM provider boundary for sentiment, forecaster, and RAG features. · `finogrid/fingpt_integration`
- [Database](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/database): schema/models · SQL migrations and domain models for routing, execution, mandates, audits, and ledgers. · `finogrid/database`
- [TypeScript SDK](https://github.com/ai4finance-foundation/fingpt/tree/master/finogrid/sdk/typescript): client sdk · External client SDK for platform access and typed integration. · `finogrid/sdk/typescript`

## Connections

- FinGPT → Benchmarking: organizes · The repo groups benchmark training and evaluation under FinGPT.
- FinGPT → Sentiment v1: contains · Early sentiment pipeline lives within the FinGPT research stack.
- FinGPT → Sentiment v3: contains · Later sentiment iteration extends the same research line.
- FinGPT → Forecaster: contains · Forecasting and robo-advice are a separate FinGPT application track.
- FinGPT → RAG Sentiment: contains · Retrieval-augmented sentiment and instruction tuning are grouped together.
- FinGPT → Report Analysis: contains · Financial report analysis is a smaller RAG workflow.
- FinGPT → Multi-Agents: contains · Multi-agent RAG experiments and evaluations live here.
- FinGPT → Other Demos: contains · Miscellaneous downstream demos share the same LLM primitives.
- Benchmarking → Sentiment v1: evolves from · Sentiment pipeline history feeds into benchmarked task framing.
- Sentiment v1 → Sentiment v3: iterates to · Version 3 continues the sentiment line with newer training/benchmarking.
- Benchmarking → RAG Sentiment: shares tasks · Benchmark tasks overlap with instruction-tuned and retrieval-based sentiment workflows.
- Forecaster → FinGPT Bridge: uses · Forecasting can run on local FinGPT models through the platform bridge.
- RAG Sentiment → FinGPT Bridge: feeds · Retrieval and sentiment workflows can use the platform LLM bridge.
- Report Analysis → FinGPT Bridge: feeds · Document analysis can reuse the shared LLM integration boundary.
- Finogrid → Ingress API: exposes · Ingress API is the front door for platform requests.
- Ingress API → Routing Engine: dispatches · Incoming work is routed into execution paths.
- Routing Engine → Partner Exec: routes · Selected jobs are sent to partner execution.
- Partner Exec → Reconciliation: returns · Execution outcomes are reconciled back into platform state.
- Ingress API → Agent Ledger: authorizes · Protected requests depend on payment and wallet state.
- Agent Ledger → Database: persists · Ledger and wallet state are stored in the operational database.
- Routing Engine → Database: reads/writes · Routing decisions and execution metadata are persisted.
- Reconciliation → Database: updates · Reconciliation closes execution records and related state.
- Ops Console → Database: observes · Operator views inspect approvals, corridors, mandates, and ledger data.
- Corridors → MCP Integrations: integrates · Country adapters rely on external compliance and banking connectors.
- FinGPT Bridge → TypeScript SDK: exposes · Platform capabilities are surfaced to external clients through the SDK boundary.
- FinGPT Bridge → Database: consumes state · LLM-enabled platform features may read persisted operational context.
- Ops Console → Agent Ledger: oversees · Ops console provides oversight on wallet, micropay, and KYA flows.
