Content
# Financial Risk and Compliance Manager - Comprehensive Documentation
## 🎥 Video Demo
Please see the [Video Demo](https://drive.google.com/file/d/1EjwGPrUwkWldcGyMN3K-hbQrZ2SDG7CL/view?usp=sharing)
## Proprietary Software Notice
This software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, via any medium, is strictly prohibited.
## 1. Project Overview
The Financial Risk and Compliance Manager with A2A Protocol and MCP Server Architecture is a modular, multi-agent system designed to automate compliance analysis for financial institutions. It leverages the Agent-to-Agent (A2A) protocol for inter-agent communication and the Model Context Protocol (MCP) server for standardized access to Generative AI tools, such as Retrieval-Augmented Generation (RAG) and Large Language Models (LLMs). The system indexes regulation documents, retrieves relevant context, and generates detailed compliance reports through a collaborative workflow involving multiple agents. This approach offers improved accuracy, efficiency, and scalability compared to traditional compliance systems.
---
# 🧩 Architecture
The system architecture consists of the following components:
- **Streamlit Frontend:** A user-friendly interface for submitting compliance queries and viewing results.
- **MCP Server:** A centralized server that provides access to Generative AI tools, such as Retrieval-Augmented Generation (RAG) using LangChain and FAISS, and Large Language Models (LLMs), using the Model Context Protocol (MCP).
- **Agents:** A set of specialized agents, including the Profile Checker, Risk Reporter, and Compliance Querier, that collaborate using the Agent-to-Agent (A2A) protocol to perform compliance analysis.
- **Regulation PDFs:** A collection of regulatory documents that serve as the knowledge base for compliance checks, indexed by the MCP Server's RAG functionality.
---
## 🔄 System Architecture Diagram
```mermaid
sequenceDiagram
participant UI as Streamlit Frontend
participant MCP as MCP Server (Flask)
participant Agent2 as Risk Reporter
participant Agent1 as Profile Checker
participant Agent3 as Compliance Querier
UI->>Agent2: 1. Sends query (via MCP)
Agent2->>Agent1: 2. Requests client profile (A2A)
Agent1-->>Agent2: 3. Returns profile data (A2A)
Agent2->>MCP: 4. Queries regulation context
MCP-->>Agent2: 5. Returns context
Agent2->>Agent3: 6. Sends risk report (A2A)
Agent3->>MCP: 7. Queries compliance details
MCP-->>Agent3: 8. Returns compliance response
Agent3-->>Agent2: 9. Sends final report (A2A)
Agent2-->>UI: 10. Returns result (via MCP)
```
**Notes on the Diagram**:
- **A2A Communication**: Direct Agent-to-Agent interactions (e.g., Agent 2 to Agent 1, Agent 2 to Agent 3) are shown using the A2A protocol.
- **MCP Server Role**: The MCP Server acts as a centralized hub, providing access to RAG services (using LangChain and FAISS) and LLMs. Agents interact with the MCP Server to retrieve regulation context and compliance details.
- **Integrated RAG Services**: The RAG functionality is embedded within the MCP Server, which indexes regulation documents and handles retrieval requests from agents.
---
## 2. A2A Communication Protocol
### 2.1 What is A2A Protocol?
The Agent-to-Agent (A2A) protocol is a standardized communication framework that enables autonomous agents to interact and collaborate with each other. In this project, we implement A2A protocol to facilitate seamless communication between specialized agents, each responsible for different aspects of compliance analysis.
### 2.2 A2A Implementation in This Project
Our system implements A2A protocol through:
1. **Direct HTTP Communication**
- Agents communicate directly with each other using RESTful HTTP endpoints
- Each agent exposes specific endpoints for receiving and sending data
- Communication follows a standardized JSON message format
2. **Agent Communication Flow**
- **Profile Checker → Risk Reporter**: Sends client profile analysis results
- **Risk Reporter → Compliance Querier**: Transmits risk assessment data
- **Compliance Querier → Risk Reporter**: Returns compliance analysis results
### 2.3 Agent Communication Matrix
| From Agent | To Agent | Communication Type | Purpose |
| ------------------ | ------------------ | ------------------ | ----------------------------------------- |
| Risk Reporter | Profile Checker | Request | Get client profile analysis |
| Profile Checker | Risk Reporter | Response | Send profile analysis results |
| Risk Reporter | Compliance Querier | Request | Send risk assessment for compliance check |
| Compliance Querier | Risk Reporter | Response | Return compliance analysis results |
### 2.4 A2A Protocol Benefits
- **Decoupled Architecture**: Agents can be developed and maintained independently
- **Scalability**: New agents can be added without modifying existing ones
- **Fault Tolerance**: Individual agent failures don't affect the entire system
- **Standardized Communication**: Consistent message format across all agents
- **Traceability**: Each communication is logged with timestamps and metadata
---
## 3. Core Components
### 3.1 Frontend (app.py)
- Built using Streamlit
- Provides a user-friendly interface for submitting compliance queries
- Displays results in a modern, card-based UI
- Allows configuration of RAG settings and other parameters
### 3.2 MCP Server (mcp_server.py)
- Acts as a centralized hub for AI services
- Implements Retrieval-Augmented Generation (RAG) using LangChain and FAISS
- Manages access to Large Language Models (LLMs)
- Handles document indexing and retrieval
### 3.3 Agent System (A2A Protocol)
The system uses three specialized agents that communicate using the A2A protocol:
1. **Profile Checker (agent1_profile_checker.py)**
- Port: 5001
- Role: Analyzes client profiles from JSON files
- Location: `client/` directory
- Purpose: Validates and processes client information
2. **Risk Reporter (agent2_risk_reporter.py)**
- Port: 5002
- Role: Coordinates the compliance analysis workflow
- Communicates with other agents
- Generates risk assessment reports
3. **Compliance Querier (agent3_compliance_querier.py)**
- Port: 5003
- Role: Performs detailed compliance checks
- Queries regulatory documents
- Generates compliance reports
### 3.4 Data Components
#### PDF Files (in data/ directory)
The system uses several regulatory documents:
- `aml_bsa_manual.pdf`: FFIEC BSA/AML Examination Manual
- `aml_31cfr.pdf`: 31 CFR Chapter X – BSA Regulations
- `sec_iaa40.pdf`: Investment Advisers Act of 1940
- `sec_rule_206_4_1.pdf`: SEC Rule 206(4)-1
These PDFs serve as the knowledge base for compliance checks and are indexed by the MCP Server's RAG functionality.
#### JSON Files (in client/ directory)
- Contains client profile data
- Used by the Profile Checker agent
- Structured data for compliance analysis
---
## 4. Workflow
1. **Query Submission**
- User submits a compliance query through the Streamlit UI
- Query is sent to the Risk Reporter agent via MCP Server
2. **Profile Analysis**
- Risk Reporter requests client profile from Profile Checker
- Profile Checker analyzes the client JSON data
- Results are returned to Risk Reporter
3. **Regulation Context**
- Risk Reporter queries MCP Server for relevant regulation context
- MCP Server uses RAG to find relevant sections from PDFs
- Context is returned to Risk Reporter
4. **Compliance Analysis**
- Risk Reporter sends data to Compliance Querier
- Compliance Querier performs detailed compliance checks
- Final report is generated and returned to UI
---
## 5. Technical Implementation
### 5.1 A2A Protocol
- Agents communicate directly with each other using HTTP
- Each agent runs on a different port (5001-5003)
- Communication is standardized and follows a specific protocol
### 5.2 RAG Implementation
- Uses LangChain for document processing
- FAISS for vector storage and similarity search
- PDFs are chunked and indexed for efficient retrieval
### 5.3 Configuration
- Environment variables for API keys
- Configurable RAG settings (chunk size, overlap)
- Modular design for easy extension
---
## 6. Setup and Usage
### 6.1 Installation
1. **Clone the repository:**
```sh
git clone https://github.com/sachin0034/Financial-Risk-and-Compliance-Manager---A2A.git
cd Financial-Risk-and-Compliance-Manager---A2A
```
2. **Install dependencies:**
```sh
pip install -r requirements.txt
```
Or, if using Poetry or pip-tools, use `pyproject.toml`.
### 6.2 Starting Services
1. **Prepare regulation files:**
- Place your regulation PDFs in the `data/` directory.
2. **Prepare client profiles:**
- Place your client JSON files in the `client/` directory.
3. **Set environment variables (if needed):**
- For example, for OpenAI:
```sh
export OPENAI_API_KEY=your-openai-api-key
```
- You can also use a `.env` file.
4. **Start the MCP server:**
```sh
python mcp_server.py
```
5. **Start the agents (in separate terminals or as background processes):**
```sh
python agents/agent1_server.py
python agents/agent2_server.py
python agents/agent3_server.py
```
6. **Run the Streamlit UI:**
```sh
streamlit run app.py
```
7. **Access the application:**
- Open your browser and go to: [http://localhost:8501](http://localhost:8501)
### 6.3 Service Ports
| Component | Command | Default Port |
| -------------------- | -------------------------------- | ------------ |
| MCP Server | `python mcp_server.py` | 5000 |
| Agent 1 (Profile) | `python agents/agent1_server.py` | 5001 |
| Agent 2 (Risk) | `python agents/agent2_server.py` | 5002 |
| Agent 3 (Compliance) | `python agents/agent3_server.py` | 5003 |
| Streamlit UI | `streamlit run app.py` | 8501 |
---
## 7. Configuration
### 7.1 File Structure
- **Client profiles:** Place JSON files in the `client/` directory
- **Regulation Data:** Place in `data/` directory
- **RAG settings:** Configure chunk size, overlap, and vector DB in the UI sidebar
- **Environment variables:** Use a `.env` file for API keys (e.g., OpenAI, Google Cloud)
### 7.2 Environment Variables
Create a `.env` file with the following variables:
```env
OPENAI_API_KEY=your-openai-api-key
```
